[#446] Add OpenAPI to template

.gitignore.rb

@@ -10,5 +10,8 @@
 
     # Ignore the test coverage results from SimpleCov
     /coverage
+
+    # Ignore generated OpenAPI file
+    /public/openapi.yml
   IGNORE
 end

.spectral.yml

@@ -0,0 +1,6 @@
+extends: ["spectral:oas"]
+
+rules:
+  oas3-unused-component: false
+  operation-operationId: false
+  info-contact: false

.template/addons/docs/openapi/examples/responses/health.json

@@ -0,0 +1,24 @@
+{
+  "ok": {
+    "value": {
+      "data": {
+        "id": "1",
+        "type": "health",
+        "attributes": {
+          "message": "OK"
+        }
+      }
+    }
+  },
+  "error": {
+    "value": {
+      "errors": [
+        {
+          "status": "500",
+          "title": "Internal Server Error",
+          "detail": "Something went wrong."
+        }
+      ]
+    }
+  }
+}

.template/addons/docs/openapi/openapi.yml

@@ -0,0 +1,31 @@
+---
+openapi: 3.0.0
+info:
+  title: API Documentation
+  description: This is the API documentation for the mock server.
+  version: 1.0.0
+
+servers:
+  - url: http://localhost:8080/api/v1
+    description: Development Base URL
+
+security:
+  - BearerAuth: []
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    $ref: "schemas.yml"
+  responses:
+    $ref: "responses.yml"
+
+paths:
+  /health:
+    $ref: "paths/health.yml"
+
+tags:
+  - name: Status
+    description: Status APIs of the project

.template/addons/docs/openapi/paths/health.yml

@@ -0,0 +1,20 @@
+---
+get:
+  tags:
+    - Status
+  security: []
+  summary: Get the status of the application.
+  description: Call this API to get the status of the application.
+
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas.yml#/responses_health'
+          examples:
+            $ref: '../examples/responses/health.json'
+
+    default:
+      $ref: '../responses.yml#/responses_default_error'

.template/addons/docs/openapi/responses.yml

@@ -0,0 +1,3 @@
+---
+responses_default_error:
+  $ref: "responses/default_error.yml"

.template/addons/docs/openapi/responses/default_error.yml

@@ -0,0 +1,11 @@
+---
+description: Default Error
+
+content:
+  application/json:
+    schema:
+      $ref: '../schemas.yml#/error'
+    example:
+      errors:
+        - code: 'invalid_request'
+          detail: 'The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.'

.template/addons/docs/openapi/schemas.yml

@@ -0,0 +1,12 @@
+---
+#### REQUESTS ####
+
+#### RESPONSES ####
+
+responses_health:
+  $ref: "schemas/responses/health.yml"
+
+#### REUSABLE SCHEMAS ####
+
+error:
+  $ref: "schemas/shared/error.yml"

.template/addons/docs/openapi/schemas/responses/health.yml

@@ -0,0 +1,24 @@
+---
+type: object
+
+description: A response body for the health API
+
+properties:
+  data:
+    type: object
+    description: The data object
+    properties:
+      id:
+        type: string
+        description: The identifier of the health
+        example: "123"
+      type:
+        type: string
+        description: The type of the health
+        example: 'health'
+      attributes:
+        type: object
+        properties:
+          message:
+            type: string
+            description: The message description of the status

.template/addons/docs/openapi/schemas/shared/error.yml

@@ -0,0 +1,15 @@
+type: object
+
+properties:
+  errors:
+    type: array
+    maxItems: 10
+    items:
+      type: object
+      properties:
+        code:
+          type: string
+          description: an application-specific error code
+        detail:
+          type: string
+          description: "a human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized."

.template/addons/github/.github/workflows/lint_docs.yml.tt

@@ -0,0 +1,31 @@
+name: Lint OpenAPI docs
+
+on: pull_request
+
+concurrency:
+  group: {{ "${{ github.workflow }}-${{ github.ref }}" }}
+  cancel-in-progress: true
+
+jobs:
+  docs_lint:
+    name: Run lint for API docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up node and restore cached dependencies
+        uses: actions/setup-node@v3
+        with:
+          node-version: "18.x"
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Generate API docs
+        run: npm run build:docs
+
+      - name: Run API docs linters
+        run: npm run lint:docs:public

.template/variants/web/.eslintrc

@@ -1,6 +1,7 @@
 {
   "extends": [
-    "@nimblehq/eslint-config-nimble"
+    "@nimblehq/eslint-config-nimble",
+    "plugin:yml/recommended"
   ],
   "globals": {
     "I18n": true

.template/variants/web/package.json.rb

@@ -32,6 +32,9 @@
 run 'yarn add --dev stylelint'
 run 'yarn add --dev @nimblehq/[email protected]'
 run 'yarn add --dev @nimblehq/[email protected]'
+run 'yarn add --dev @apidevtools/[email protected]'
+run 'yarn add --dev @stoplight/[email protected]'
+run 'yarn add --dev [email protected]'
 
 # Setup scripts
 run 'npm pkg set scripts.eslint="eslint . --color"'
@@ -40,6 +43,11 @@
 run 'npm pkg set scripts.stylelint:fix="stylelint **/*.scss --color --fix"'
 run 'npm pkg set scripts.codebase="yarn eslint && yarn stylelint"'
 run 'npm pkg set scripts.codebase:fix="yarn eslint:fix && yarn stylelint:fix"'
+run 'npm pkg set scripts.lint:docs:yml="eslint docs/openapi --ext .yml --color"'
+run 'npm pkg set scripts.lint:docs:openapi="spectral lint docs/openapi/openapi.yml -F error"'
+run 'npm pkg set scripts.lint:docs:dev="npm lint:docs:yml && npm lint:docs:openapi"'
+run 'npm pkg set scripts.lint:docs:public="npm build:docs && eslint public/openapi.yml --color --no-ignore && spectral lint public/openapi.yml -F error"'
+run 'npm pkg set scripts.build:docs="swagger-cli bundle docs/openapi/openapi.yml --outfile public/openapi.yml --type yaml"'
 
 source_stylesheet = 'app/assets/stylesheets/application.scss'
 bundled_stylesheet = 'app/assets/builds/application.css'

Makefile.tt

@@ -1,6 +1,6 @@
 include .env
 
-.PHONY: dev env/setup env/teardown codebase codebase/fix
+.PHONY: dev env/setup env/teardown codebase codebase/fix doc/generate
 
 dev:
 	make install-dependencies
@@ -25,3 +25,6 @@ codebase:
 codebase/fix:
 	rubocop -a
 	yarn codebase:fix
+
+doc/generate:
+  yarn run build:docs

template.rb

@@ -36,6 +36,7 @@ def apply_template!(template_root)
   copy_file 'Dangerfile'
   copy_file '.rubocop.yml'
   copy_file '.reek.yml'
+  copy_file '.spectral.yml'
 
   template '.ruby-gemset.tt'
   template '.ruby-version.tt', force: true