feat(doc): Improve documentation generation and display (#64)

* Create new documentation architecture
* Rename documentation folder to doc

.github/workflows/backend-ci-push-pre-prod-documentation.yml

@@ -1,19 +1,19 @@
-name: Build and push preprod documentation's images CI
+name: Build and push preprod doc's images CI
 # This workflow is triggered on tag push finishing with '-preprod'
 on:
   push:
     tags:
       - v*-preprod
 
 jobs:
-  build-and-push-documentation:
-    name: Docker Build Documentation and push image
+  build-and-push-doc:
+    name: Docker Build doc and push image
     runs-on: ubuntu-18.04
     steps:
       - name: Checkout code
         uses: actions/checkout@v2
 
-      - name: Build and push Documentation Docker image with tag number
+      - name: Build and push doc Docker image with tag number
         # Official docker action: https://github.com/docker/build-push-action
         uses: docker/build-push-action@v1.1.0
         with:
@@ -22,12 +22,12 @@ jobs:
           registry: docker.pkg.github.com
           # github.repository -> alexandr-io/backend
           # https://github.com/docker/build-push-action/pull/14/files/d1c5c2f87bcd65b263d72ea6b1861bb25cbbcda5#r429877166
-          repository: ${{github.repository}}/documentation
+          repository: ${{github.repository}}/doc
           tag_with_ref: true
-          path: microservices/documentation/app
+          path: microservices/doc/app
           push: true
 
-      - name: Build and push Documentation Docker image with tag latest-preprod
+      - name: Build and push doc Docker image with tag latest-preprod
         # Official docker action: https://github.com/docker/build-push-action
         uses: docker/build-push-action@v1.1.0
         with:
@@ -36,15 +36,15 @@ jobs:
           registry: docker.pkg.github.com
           # github.repository -> alexandr-io/backend
           # https://github.com/docker/build-push-action/pull/14/files/d1c5c2f87bcd65b263d72ea6b1861bb25cbbcda5#r429877166
-          repository: ${{github.repository}}/documentation
+          repository: ${{github.repository}}/doc
           tags: latest-preprod
-          path: microservices/documentation/app
+          path: microservices/doc/app
           push: true
 
-      - name: Deploy or redeploy documentation app
+      - name: Deploy or redeploy doc app
         uses: cross-the-world/ssh-pipeline@master
         with:
           host: ${{ secrets.HOST_PREPROD }}
           user: ${{ secrets.HOST_PREPROD_USERNAME }}
           pass: ${{ secrets.HOST_PREPROD_PASSWORD }}
-          script: /kubernetes/app-deployment.sh documentation
+          script: /kubernetes/app-deployment.sh doc

.github/workflows/backend-ci-push-prod-documentation.yml

@@ -1,19 +1,19 @@
-name: Build and push preprod documentation's images CI
+name: Build and push preprod doc's images CI
 # This workflow is triggered on tag push finishing with '-preprod'
 on:
   push:
     tags-ignore:
       - 'v*-*'
 
 jobs:
-  build-and-push-documentation:
-    name: Docker Build Documentation and push image
+  build-and-push-doc:
+    name: Docker Build doc and push image
     runs-on: ubuntu-18.04
     steps:
       - name: Checkout code
         uses: actions/checkout@v2
 
-      - name: Build and push Documentation Docker image with tag number
+      - name: Build and push doc Docker image with tag number
         # Official docker action: https://github.com/docker/build-push-action
         uses: docker/build-push-action@v1.1.0
         with:
@@ -22,12 +22,12 @@ jobs:
           registry: docker.pkg.github.com
           # github.repository -> alexandr-io/backend
           # https://github.com/docker/build-push-action/pull/14/files/d1c5c2f87bcd65b263d72ea6b1861bb25cbbcda5#r429877166
-          repository: ${{github.repository}}/documentation
+          repository: ${{github.repository}}/doc
           tag_with_ref: true
-          path: microservices/documentation/app
+          path: microservices/doc/app
           push: true
 
-      - name: Build and push Documentation Docker image with tag latest-preprod
+      - name: Build and push doc Docker image with tag latest-preprod
         # Official docker action: https://github.com/docker/build-push-action
         uses: docker/build-push-action@v1.1.0
         with:
@@ -36,15 +36,15 @@ jobs:
           registry: docker.pkg.github.com
           # github.repository -> alexandr-io/backend
           # https://github.com/docker/build-push-action/pull/14/files/d1c5c2f87bcd65b263d72ea6b1861bb25cbbcda5#r429877166
-          repository: ${{github.repository}}/documentation
+          repository: ${{github.repository}}/doc
           tags: latest
-          path: microservices/documentation/app
+          path: microservices/doc/app
           push: true
 
-      - name: Deploy or redeploy documentation app
+      - name: Deploy or redeploy doc app
         uses: cross-the-world/ssh-pipeline@master
         with:
           host: ${{ secrets.HOST_PROD }}
           user: ${{ secrets.HOST_PROD_USERNAME }}
           pass: ${{ secrets.HOST_PROD_PASSWORD }}
-          script: /kubernetes/app-deployment.sh documentation
+          script: /kubernetes/app-deployment.sh doc

.github/workflows/documentation-ci-build.yml

@@ -1,26 +1,26 @@
-name: Documentation service build CI
-# This workflow is triggered on pushes to the /microservices/documentation/app/ directory.
+name: doc service build CI
+# This workflow is triggered on pushes to the /microservices/doc/app/ directory.
 # The workflow does not trigger on main and pre-prod branch
 on:
   push:
     paths:
-      - 'microservices/documentation/app/**'
+      - 'microservices/doc/app/**'
     branches-ignore:
       - master
 
 jobs:
   build:
-    name: Docker Build Documentation
+    name: Docker Build doc
     runs-on: ubuntu-18.04
     steps:
       - name: Checkout code
         uses: actions/checkout@v2
 
-      - name: Build Documentation Docker image
+      - name: Build doc Docker image
         # Official docker action: https://github.com/docker/build-push-action
         uses: docker/build-push-action@v1.1.0
         with:
           # github.repository -> alexandr-io/backend
           repository: ${{github.repository}}
-          path: microservices/documentation/app
+          path: microservices/doc/app
           push: false

docker-compose.yml

@@ -138,17 +138,17 @@ services:
     env_file: .env-dev
     restart: unless-stopped
 
-  # Documentation service
-  documentation:
-    container_name: documentation
+  # Doc service
+  doc:
+    container_name: doc
     build:
-      context: microservices/documentation/app
+      context: microservices/doc/app
       dockerfile: Dockerfile-dev
     env_file: .env-dev
     ports:
       - "4000:3000"
     volumes:
-      - "./microservices/documentation/app:/app"
+      - "./microservices/doc/app:/app"
 
   # Library service
   library:

microservices/doc/app/.gitignore

@@ -0,0 +1 @@
+merged/**.yml

microservices/documentation/app/Dockerfile → microservices/doc/app/Dockerfile

@@ -13,12 +13,12 @@ RUN go mod download
 
 COPY . ./
 
-RUN go build -a -installsuffix cgo -ldflags '-extldflags "-static"' -o alexandrio-backend-documentation .
+RUN go build -a -installsuffix cgo -ldflags '-extldflags "-static"' -o alexandrio-backend-doc .
 
 
 # Run stage
 FROM scratch
 
 COPY --from=builder /app/ ./
 
-ENTRYPOINT ["./alexandrio-backend-documentation"]
+ENTRYPOINT ["./alexandrio-backend-doc"]

microservices/doc/app/auth.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"github.com/go-openapi/runtime/middleware"
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp/fasthttpadaptor"
+)
+
+const auth = "auth"
+
+func wrapAuthDocHandler() func(ctx *fiber.Ctx) error {
+	swaggerHandler := middleware.Redoc(fillRedocOpts(auth), nil)
+
+	return func(ctx *fiber.Ctx) error {
+		fasthttpadaptor.NewFastHTTPHandler(swaggerHandler)(ctx.Context())
+		return nil
+	}
+}
+
+func mergeAuthFiles(ctx *fiber.Ctx) error {
+	if err := mergeDocsFiles(ctx, auth); err != nil {
+		return err
+	}
+	return ctx.Next()
+}

microservices/doc/app/auth/info.yml

@@ -0,0 +1,18 @@
+---
+openapi: 3.0.2
+info:
+  description: "Documentation for the Alexandrio's AUTH microsecervice REST API\n\n
+                <b>You can find the documentation of the others MS in these pages:</b>\n\n
+                <a href=\"{{ .Auth }}\" class=\"sc-fzooss bFAotz\">Auth</a>
+                <a href=\"{{ .User }}\" class=\"sc-fzooss bFAotz\">User</a>
+                <a href=\"{{ .Library }}\" class=\"sc-fzooss bFAotz\">Library</a>
+                <a href=\"{{ .Media }}\" class=\"sc-fzooss bFAotz\">Media</a>"
+  version: v1
+  title: AUTH Documentation
+tags:
+  - name: AUTHENTICATION
+  - name: INVITATION
+  - name: RESET PASSWORD
+    description: "Schema of reset password workflow: <img src=\"https://i.imgur.com/qrqkPtO.png\" />"
+paths:
+

microservices/documentation/app/auth/paths/auth.yml → microservices/doc/app/auth/paths/auth.yml

@@ -10,11 +10,11 @@ paths:
         "401":
           $ref: '#/components/schemas/UnauthorizedErrorResponse'
       security:
-        - Bearer Auth: []
+        - bearerAuth: []
       servers:
         - url: //auth.alexandrio.cloud
           description: Production server
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - AUTHENTICATION

microservices/documentation/app/auth/paths/invitation.yml → microservices/doc/app/auth/paths/invitation.yml

@@ -13,14 +13,14 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - INVITATION
 
   /invitation/{token}:
     delete:
       description: Delete an invitation corresponding to the given `token`. For test purpose only.
       summary: Delete Invitation
       security:
-        - Bearer Auth: []
+        - bearerAuth: []
       responses:
         "204":
           $ref: '#/components/schemas/NoContentResponse'
@@ -32,4 +32,4 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - INVITATION

microservices/documentation/app/auth/paths/login.yml → microservices/doc/app/auth/paths/login.yml

@@ -21,4 +21,4 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - AUTHENTICATION

microservices/documentation/app/auth/paths/logout.yml → microservices/doc/app/auth/paths/logout.yml

@@ -10,11 +10,11 @@ paths:
         "401":
           $ref: '#/components/schemas/UnauthorizedErrorResponse'
       security:
-        - Bearer Auth: [ ]
+        - bearerAuth: []
       servers:
         - url: //auth.alexandrio.cloud
           description: Production server
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - AUTHENTICATION

microservices/documentation/app/auth/paths/passwordReset.yml → microservices/doc/app/auth/paths/passwordReset.yml

@@ -23,10 +23,10 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - RESET PASSWORD
 
     get:
-      description: "Check if the reset password token is valid and get user info.\n\nSchema of reset password workflow: <img src=\"https://i.imgur.com/qrqkPtO.png\" />"
+      description: "Check if the reset password token is valid and get user info."
       summary: Check Reset Token
       requestBody:
         content:
@@ -43,7 +43,7 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - RESET PASSWORD
 
     put:
       description: Final step of password reset, after asking and checking a reset password token.
@@ -63,4 +63,4 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - RESET PASSWORD

microservices/documentation/app/auth/paths/refresh.yml → microservices/doc/app/auth/paths/refresh.yml

@@ -23,4 +23,4 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - AUTHENTICATION

microservices/documentation/app/auth/paths/register.yml → microservices/doc/app/auth/paths/register.yml

@@ -21,4 +21,4 @@ paths:
         - url: //auth.preprod.alexandrio.cloud
           description: Preprod server
       tags:
-        - AUTH
+        - AUTHENTICATION

microservices/documentation/app/security.yml → microservices/doc/app/auth/security.yml

@@ -1,9 +1,9 @@
 ---
 components:
   securitySchemes:
-    Bearer Auth:
+    bearerAuth:
       description: "Alexandrio backend is using both auth token and refresh token.\n\nThe auth token is used to access resources as an authenticated user. This token is only valid for 15 minutes for security purposes.  \nThe auth token is given by the [`/register`](#operation/register), [`/login`](#operation/login) and [`/auth/refresh`](#operation/refresh_token) routes.  \nYou need to send the auth token as a Bearer authentication token in the header of the request to access protected routes.\n\nThe refresh token is used to get a new auth token. When the auth token is expired, you need to send this refresh token to [`/auth/refresh`](#operation/refresh_token) to get a new auth and refresh token.  \nThe refresh token is valid for 30 days and can be used only once. The [`/auth/refresh`](#operation/refresh_token) route return a new refresh token.\n\n<div align=\"center\">\n  <img alt=\"Workflow\" src=\"https://i.imgur.com/ldrebnu.png\" />\n</div>\n<center><p style=\"font-size:11px\">Schema of the authentication workflow</p></center>\n"
-      type: https
+      type: http
       scheme: bearer
       bearerFormat: JWT
 

microservices/doc/app/docs/info.yml

@@ -0,0 +1,25 @@
+---
+openapi: 3.0.2
+info:
+  description: "Documentation for the Alexandrio's microsecervice REST API\n\n
+                <b>You can find the documentation of the microservices in these pages:</b>\n\n
+                <a href=\"{{ .Auth }}\" class=\"sc-fzooss bFAotz\">Auth</a>
+                <a href=\"{{ .User }}\" class=\"sc-fzooss bFAotz\">User</a>
+                <a href=\"{{ .Library }}\" class=\"sc-fzooss bFAotz\">Library</a>
+                <a href=\"{{ .Media }}\" class=\"sc-fzooss bFAotz\">Media</a>"
+  version: v1
+  title: Alexandrio Documentation
+paths:
+  /ping:
+    get:
+      description: Check whether or not a service is running
+      responses:
+        '200':
+          description: The service is running
+      servers:
+        - url: //service.alexandrio.cloud
+          description: Production server
+        - url: //service.preprod.alexandrio.cloud
+          description: Preprod server
+      tags:
+        - PING

microservices/documentation/app/go.mod → microservices/doc/app/go.mod

@@ -1,4 +1,4 @@
-module github.com/alexandr-io/backend/documentation
+module github.com/alexandr-io/backend/doc
 
 go 1.15