Merge pull request #13 from canonical/html-openapi-schema

Generate OpenAPI schema in HTML format as part of pre-commit hook

.github/workflows/openapi_gh_pages.yaml

@@ -31,7 +31,7 @@ jobs:
         with:
           node-version: '20.x'
       - run: mkdir -p dist
-      - run: npx @redocly/cli build-docs ./openapi.yaml -o ./dist/index.html
+      - run: npx @redocly/cli build-docs ./schemas/openapi.yaml -o ./dist/index.html
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/test_server.yaml

@@ -45,4 +45,4 @@ jobs:
         run: curl http://localhost:8001/v1/openapi.yaml -o fetched_openapi.yaml
 
       - name: Compare with repository's openapi.yaml
-        run: diff fetched_openapi.yaml openapi.yaml
+        run: diff fetched_openapi.yaml schemas/openapi.yaml

.pre-commit-config.yaml

@@ -1,9 +1,15 @@
 repos:
 -   repo: local
     hooks:
-    -   id: openapi-fetch
-        name: Fetch OpenAPI YAML
-        entry: scripts/fetch_openapi.sh
-        language: script
-        always_run: true
-        pass_filenames: false
+    - id: openapi-fetch-yaml
+      name: Fetch OpenAPI YAML
+      entry: scripts/fetch_openapi_yaml.sh
+      language: script
+      always_run: true
+      pass_filenames: false
+    - id: openapi-generate-html
+      name: Generate OpenAPI HTML schema
+      entry: scripts/generate_openapi_html.sh
+      language: script
+      always_run: true
+      pass_filenames: false

scripts/fetch_openapi.sh → scripts/fetch_openapi_yaml.sh

@@ -9,10 +9,10 @@ poetry run uvicorn hwapi.main:app --port 8002 &
 sleep 5
 
 # Fetch OpenAPI YAML
-curl http://localhost:8002/v1/openapi.yaml -o openapi.yaml
+curl http://localhost:8002/v1/openapi.yaml -o schemas/openapi.yaml
 
 # Kill the FastAPI server
 kill $!
 
 # Add schema to the committed files
-git add openapi.yaml
+git add schemas/openapi.yaml

scripts/generate_openapi_html.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+cd server/schemas/
+
+# Generate HTML schema
+npx @redocly/cli build-docs openapi.yaml -o openapi.html
+
+git add openapi.html

server/README.md

@@ -15,16 +15,26 @@ Then you can access the server via this URL: http://127.0.0.1:8000
 
 ## Accessing API schema
 
-To access the HTML view for the API schema, just run the server and follow the [/#docs](http://127.0.0.1:8000/#docs) endpoint.
+You can retrieve API schema in HTML, YAML, and JSON formats:
 
-For getting its JSON version, follow the [/openapi.json](http://127.0.0.1:8000/openapi.json) endpoint. 
-
-You can retrieve the schema in the YAML format by following the [/openapi.yaml](http://127.0.0.1:8000/v1/openapi.yaml) endpoint ior just reading the [openapi.yaml](./openapi.yaml) file in the repo.
+- To access the HTML view for the API schema, just run the server and follow the [/#docs](http://127.0.0.1:8000/#docs) endpoint.
+- A self-contained HTML representation of the schema is also included in the repository: [openapi.html](./schemas/openapi.html).
+- Retrieve the schema in YAML from the running service by following the [/openapi.yaml](http://127.0.0.1:8000/v1/openapi.yaml) endpoint
+- A copy of the [openapi.yaml](./schemas/openapi.yaml) is included in the repo, and it is enforced by a CI automation to be up to date.
+- For getting its JSON version, follow the [/openapi.json](http://127.0.0.1:8000/openapi.json) endpoint.
 
 ## Development
 
 ### Pre-commit hooks
 
 The repo contains pre-commit hook rules to update the openapi.yaml file before committing the changes. To use it, first make sure `pre-commit` is installed on your system (is installed with poetry dev dependencies).
 
+For generating OpenAPI schema in HTML format, you need Node.js to be installed on your system:
+
+```bash
+# Install Node.js v20
+$ curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+$ sudo apt-get install -y nodejs
+```
+
 Then go to the `server/` directory and run `poetry run pre-commit install`.