ci: genrate api documentation

.github/workflows/generate-pdf.yml

@@ -0,0 +1,32 @@
+name: generate-api-documentation
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  make:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Sage
+        uses: einride/sage/actions/setup@master
+        with:
+          go-version: 1.19
+
+      - name: Setup Node
+        # Latest version `v3.7.0` contains a bug, see the following issue:
+        # https://github.com/actions/setup-node/issues/801
+        uses: actions/setup-node@v3.6.0
+        with:
+          node-version: 18
+          #registry-url: https://registry.npmjs.org
+          #cache: "yarn"
+          #cache-dependency-path: frontend/yarn.lock
+
+      - name: Generate PDF's
+        run: make generate-pdf
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: auth-pdf
+          path: auth.pdf

.sage/main.go

@@ -82,3 +82,25 @@ func ServePDF(ctx context.Context) error {
 		Handler: httpMux,
 	}).ListenAndServe()
 }
+
+func GeneratePDF(ctx context.Context) error {
+	sg.SerialDeps(ctx, installRapiPDFCLI, generateAuthPDF)
+	return nil
+}
+
+func installRapiPDFCLI(ctx context.Context) error {
+	cmd := sg.Command(ctx, "yarn", "add", "@kingjan1999/rapipdf-cli")
+	return cmd.Run()
+}
+
+func generateAuthPDF(ctx context.Context) error {
+	cmd := sg.Command(
+		ctx,
+		"yarn",
+		"rapipdf",
+		"--configFile=rapipdf.json",
+		"--outputFile=auth.pdf",
+		"openapiv2/auth.swagger.yaml",
+	)
+	return cmd.Run()
+}

Makefile

@@ -59,6 +59,10 @@ format-markdown: $(sagefile)
 format-yaml: $(sagefile)
 	@$(sagefile) FormatYaml
 
+.PHONY: generate-pdf
+generate-pdf: $(sagefile)
+	@$(sagefile) GeneratePDF
+
 .PHONY: git-verify-no-diff
 git-verify-no-diff: $(sagefile)
 	@$(sagefile) GitVerifyNoDiff

rapipdf.json

@@ -0,0 +1,58 @@
+{
+  "pdfSortTags": true,
+  "localize": {
+    "index": "INDEX",
+    "api": "API",
+    "apiList": "API List",
+    "apiReference": "API Referenz",
+    "apiVersion": "API Version",
+    "contact": "KONTAKT",
+    "name": "NAME",
+    "email": "EMAIL",
+    "url": "URL",
+    "termsOfService": "Nutzungsbedingungen",
+    "securityAndAuthentication": "Sicherheit und Authentifizierung",
+    "securitySchemes": "SICHERHEIT SCHEMAS",
+    "key": "SCHLÜSSEL",
+    "type": "TYP",
+    "example": "BEISPIEL",
+    "description": "BESCHREIBUNG",
+    "request": "REQUEST",
+    "requestBody": "REQUEST BODY",
+    "response": "RESPONSE",
+    "responseModel": "RESPONSE MODEL",
+    "statusCode": "STATUS CODE",
+    "deprecated": "VERALTET",
+    "allowed": "ERLAUBT",
+    "default": "DEFAULT",
+    "readOnly": "READ ONLY",
+    "writeOnly": "WRITE ONLY",
+    "enumValues": "ENUM",
+    "pattern": "PATTERN",
+    "parameters": "Parameter",
+    "noRequestParameters": "Keine request parameter",
+    "method": "METHOD",
+    "pageNumber": "%d von %d",
+    "createdDate": "Generiert am: %3$s.%2$s.%1$s"
+  },
+  "pdfStyles": {
+    "gray": {"color": "#b1b1b1"},
+    "darkgray": {"color": "#868686"},
+    "lightgray": {"color": "#d9d9d9"}
+  },
+  "pdfFonts": {
+  },
+  "pdfPrimaryColor": "#e0003c",
+  "pdfAlternateColor": "#565656",
+  "pdfTitle": "API Referenz",
+  "pdfCoverText": "Cover-Text",
+  "pdfSchemaStyle": "object",
+  "includeToc": true,
+  "includeApiList": false,
+  "includeApiDetails": true,
+  "includeSecurity": true,
+  "includeInfo": true,
+  "includeExample": true,
+  "logoTop": "imgs/logo-top.png",
+  "logoBottom": "imgs/logo-bottom.png"
+}