feat(agora): add OpenAPI description and docs site (#2766)

Sage-Bionetworks · Aug 21, 2024 · 0313887 · 0313887
1 parent 7643b94
commit 0313887
Show file tree

Hide file tree

Showing 27 changed files with 511 additions and 0 deletions.
diff --git a/apps/agora/api-docs/.env.example b/apps/agora/api-docs/.env.example
@@ -0,0 +1 @@
+PORT=8010
diff --git a/apps/agora/api-docs/Dockerfile b/apps/agora/api-docs/Dockerfile
@@ -0,0 +1,9 @@
+FROM redocly/redoc:v2.0.0
+
+HEALTHCHECK --interval=2s --timeout=3s --retries=5 --start-period=2s \
+  CMD curl --fail --silent "localhost:8010" || exit 1
+
+COPY build/redoc-static.html /usr/share/nginx/html/index.html
+COPY favicon.ico /usr/share/nginx/html/
+
+EXPOSE 8010
diff --git a/apps/agora/api-docs/favicon.ico b/apps/agora/api-docs/favicon.ico
diff --git a/apps/agora/api-docs/index.hbs b/apps/agora/api-docs/index.hbs
@@ -0,0 +1,20 @@
+<html>
+  <head>
+    <meta charset='utf8' />
+    <title>{{title}}</title>
+    <!-- needed for adaptive design -->
+    {{!-- <meta description='{{{templateOptions.metaDescription}}}' /> --}}
+    <meta name='viewport' content='width=device-width, initial-scale=1' />
+    <style>
+      body { padding: 0; margin: 0; }
+    </style>
+    {{{redocHead}}}
+    {{#unless disableGoogleFont}}<link
+        href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700'
+        rel='stylesheet'
+      />{{/unless}}
+  </head>
+  <body>
+    {{{redocHTML}}}
+  </body>
+</html>
diff --git a/apps/agora/api-docs/project.json b/apps/agora/api-docs/project.json
@@ -0,0 +1,87 @@
+{
+  "name": "agora-api-docs",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "targets": {
+    "create-config": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "cp -n .env.example .env",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "redocly build-docs --config redocly.yaml --template index.hbs --output build/redoc-static.html",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "serve": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "redocly preview-docs --config redocly.yaml --port 8010",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "serve-detach": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "docker/agora/serve-detach.sh agora-api-docs"
+      }
+    },
+    "build-image": {
+      "executor": "@nx-tools/nx-container:build",
+      "options": {
+        "context": "apps/agora/api-docs",
+        "metadata": {
+          "images": [
+            "ghcr.io/sage-bionetworks/agora-api-docs"
+          ],
+          "tags": [
+            "type=edge,branch=main",
+            "type=raw,value=local",
+            "type=sha"
+          ]
+        },
+        "push": false
+      },
+      "dependsOn": [
+        "build"
+      ]
+    },
+    "publish-image": {
+      "executor": "@nx-tools/nx-container:build",
+      "options": {
+        "context": "apps/agora/api-docs",
+        "metadata": {
+          "images": [
+            "ghcr.io/sage-bionetworks/agora-api-docs"
+          ],
+          "tags": [
+            "type=edge,branch=main",
+            "type=sha"
+          ]
+        },
+        "push": true
+      },
+      "dependsOn": [
+        "build-image"
+      ]
+    },
+    "scan-image": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "trivy image ghcr.io/sage-bionetworks/agora-api-docs:local --quiet",
+        "color": true
+      }
+    }
+  },
+  "tags": [
+    "type:docs",
+    "scope:backend"
+  ],
+  "implicitDependencies": [
+    "agora-api-description"
+  ]
+}
diff --git a/apps/agora/api-docs/redocly.yaml b/apps/agora/api-docs/redocly.yaml
@@ -0,0 +1,11 @@
+# See https://docs.redoc.ly/cli/configuration/ for more information.
+apis:
+  main:
+    root: '../../../libs/agora/api-description/build/openapi.yaml'
+# theme:
+#   openapi:
+#     theme:
+#       rightPanel:
+#         backgroundColor: '#314fa7'
+#       sidebar:
+#         backgroundColor: '#ffffff'
diff --git a/docker/agora/serve-detach.sh b/docker/agora/serve-detach.sh
@@ -2,6 +2,7 @@
 
 args=(
   # List of services in alphanumeric order
+  --file docker/agora/services/api-docs.yml
   --file docker/agora/services/app.yml
   --file docker/agora/services/data.yml
   --file docker/agora/services/mongo.yml

diff --git a/docker/agora/services/api-docs.yml b/docker/agora/services/api-docs.yml
@@ -0,0 +1,15 @@
+services:
+  agora-api-docs:
+    image: ghcr.io/sage-bionetworks/agora-api-docs:${AGORA_VERSION:-local}
+    container_name: agora-api-docs
+    restart: always
+    env_file:
+      - ../../../apps/agora/api-docs/.env
+    networks:
+      - agora
+    ports:
+      - '8010:8010'
+    deploy:
+      resources:
+        limits:
+          memory: 200M
diff --git a/libs/agora/api-description/.gitignore b/libs/agora/api-description/.gitignore
@@ -0,0 +1 @@
+!build
diff --git a/libs/agora/api-description/README.md b/libs/agora/api-description/README.md
@@ -0,0 +1,7 @@
+# api-spec
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test api-spec` to execute the unit tests.
diff --git a/libs/agora/api-description/build/openapi.yaml b/libs/agora/api-description/build/openapi.yaml
@@ -0,0 +1,87 @@
+openapi: 3.0.3
+info:
+  version: 1.0.0
+  title: Agora REST API
+  license:
+    name: Apache 2.0
+    url: https://github.com/Sage-Bionetworks/sage-monorepo/blob/main/LICENSE.txt
+  contact:
+    name: Support
+    url: https://github.com/Sage-Bionetworks/sage-monorepo
+  x-logo:
+    url: https://dev.openchallenges.io/img/unsafe/logo/OpenChallenges-logo.png
+servers:
+  - url: http://localhost/v1
+tags:
+  - name: Dataversion
+    description: Operations about dataversion.
+paths:
+  /dataversion:
+    get:
+      tags:
+        - Dataversion
+      summary: Get dataversion
+      description: Get dataversion
+      operationId: getDataversion
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dataversion'
+          description: Success
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+components:
+  schemas:
+    Dataversion:
+      type: object
+      description: A dataversion
+      properties:
+        data_file:
+          type: string
+        data_version:
+          type: string
+        team_images_id:
+          type: string
+      required:
+        - data_file
+        - data_version
+        - team_images_id
+    BasicError:
+      type: object
+      description: Problem details (tools.ietf.org/html/rfc7807)
+      properties:
+        title:
+          type: string
+          description: A human readable documentation for the problem type
+        status:
+          type: integer
+          description: The HTTP status code
+        detail:
+          type: string
+          description: A human readable explanation specific to this occurrence of the problem
+        type:
+          type: string
+          description: An absolute URI that identifies the problem type
+      required:
+        - title
+        - status
+      x-java-class-annotations:
+        - '@lombok.AllArgsConstructor'
+        - '@lombok.Builder'
+  responses:
+    BadRequest:
+      description: Invalid request
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/BasicError'
+    InternalServerError:
+      description: The request cannot be fulfilled due to an unexpected server error
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/BasicError'
diff --git a/libs/agora/api-description/openapi-lint-config.yaml b/libs/agora/api-description/openapi-lint-config.yaml
@@ -0,0 +1,4 @@
+errorsOnly: true
+summaryOnly: false
+limits:
+  warnings: 25
diff --git a/libs/agora/api-description/project.json b/libs/agora/api-description/project.json
@@ -0,0 +1,37 @@
+{
+  "name": "agora-api-description",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/agora/api-description/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "redocly bundle --output build/openapi.yaml src/openapi.yaml",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "lint-openapi --config openapi-lint-config.yaml --ruleset spectral.yaml build/openapi.yaml",
+        "cwd": "{projectRoot}"
+      },
+      "dependsOn": ["build"]
+    },
+    "format": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "prettier --write {projectRoot}"
+      }
+    },
+    "format-check": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "prettier --check {projectRoot}"
+      }
+    }
+  },
+  "tags": [],
+  "implicitDependencies": []
+}
diff --git a/libs/agora/api-description/spectral.yaml b/libs/agora/api-description/spectral.yaml
@@ -0,0 +1,6 @@
+extends: '@ibm-cloud/openapi-ruleset'
+rules:
+  ibm-enum-casing-convention: off
+  ibm-parameter-casing-convention: off
+  ibm-path-segment-casing-convention: off
+  ibm-property-casing-convention: off
diff --git a/libs/agora/api-description/src/components/README.md b/libs/agora/api-description/src/components/README.md
@@ -0,0 +1,13 @@
+# Reusable components
+
+- You can create the following folders here:
+  - `schemas` - reusable [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject)
+  - `responses` - reusable [Response Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject)
+  - `parameters` - reusable [Parameter Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject)
+  - `examples` - reusable [Example Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#exampleObject)
+  - `headers` - reusable [Header Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#headerObject)
+  - `requestBodies` - reusable [Request Body Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject)
+  - `links` - reusable [Link Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#linkObject)
+  - `callbacks` - reusable [Callback Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callbackObject)
+  - `securitySchemes` - reusable [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject)
+- Filename of files inside the folders represent component name, e.g. `Customer.yaml`
diff --git a/libs/agora/api-description/src/components/headers/ExpiresAfter.yaml b/libs/agora/api-description/src/components/headers/ExpiresAfter.yaml
@@ -0,0 +1,4 @@
+description: date in UTC when token expires
+schema:
+  type: string
+  format: date-time
diff --git a/libs/agora/api-description/src/components/responses/BadRequest.yaml b/libs/agora/api-description/src/components/responses/BadRequest.yaml
@@ -0,0 +1,5 @@
+description: Invalid request
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/BasicError.yaml
diff --git a/libs/agora/api-description/src/components/responses/Conflict.yaml b/libs/agora/api-description/src/components/responses/Conflict.yaml
@@ -0,0 +1,5 @@
+description: The request conflicts with current state of the target resource
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/BasicError.yaml
diff --git a/libs/agora/api-description/src/components/responses/InternalServerError.yaml b/libs/agora/api-description/src/components/responses/InternalServerError.yaml
@@ -0,0 +1,5 @@
+description: The request cannot be fulfilled due to an unexpected server error
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/BasicError.yaml
diff --git a/libs/agora/api-description/src/components/responses/NotFound.yaml b/libs/agora/api-description/src/components/responses/NotFound.yaml
@@ -0,0 +1,5 @@
+description: The specified resource was not found
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/BasicError.yaml
diff --git a/libs/agora/api-description/src/components/responses/Unauthorized.yaml b/libs/agora/api-description/src/components/responses/Unauthorized.yaml
@@ -0,0 +1,5 @@
+description: Unauthorized
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/BasicError.yaml
diff --git a/libs/agora/api-description/src/components/schemas/BasicError.yaml b/libs/agora/api-description/src/components/schemas/BasicError.yaml
@@ -0,0 +1,22 @@
+type: object
+description: Problem details (tools.ietf.org/html/rfc7807)
+properties:
+  title:
+    type: string
+    description: A human readable documentation for the problem type
+  status:
+    type: integer
+    description: The HTTP status code
+  detail:
+    type: string
+    description: A human readable explanation specific to this occurrence of
+      the problem
+  type:
+    type: string
+    description: An absolute URI that identifies the problem type
+required:
+  - title
+  - status
+x-java-class-annotations:
+  - '@lombok.AllArgsConstructor'
+  - '@lombok.Builder'
diff --git a/libs/agora/api-description/src/components/schemas/Dataversion.yaml b/libs/agora/api-description/src/components/schemas/Dataversion.yaml
@@ -0,0 +1,13 @@
+type: object
+description: A dataversion
+properties:
+  data_file:
+    type: string
+  data_version:
+    type: string
+  team_images_id:
+    type: string
+required:
+  - data_file
+  - data_version
+  - team_images_id
diff --git a/libs/agora/api-description/src/components/schemas/EmptyObject.yaml b/libs/agora/api-description/src/components/schemas/EmptyObject.yaml
@@ -0,0 +1,2 @@
+type: object
+description: Empty JSON object