chore: add build docs

.devcontainer/devcontainer.json

@@ -16,7 +16,8 @@
   "features": {
     "ghcr.io/devcontainers/features/docker-in-docker:2": {},
     "ghcr.io/devcontainers/features/go:1": {},
-    "ghcr.io/devcontainers/features/terraform:1": {}
+    "ghcr.io/devcontainers/features/terraform:1": {},
+    "ghcr.io/devcontainers/features/node:1": {}
   },
   "forwardPorts": [
     3000,

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+# .github/workflows/docs.yml
+
+name: Build docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+    - uses: actions/setup-node@v4
+    - run: |
+        make docs
+    - uses: peaceiris/actions-gh-pages@v4
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./public

.redocly.yaml

@@ -0,0 +1,14 @@
+# See https://redoc.ly/docs/cli/configuration/ for more information.
+apiDefinitions:
+  main: <%= mainDefinitionFile %>
+lint:
+  extends:
+    - recommended
+  rules:
+    no-unused-components: warning
+referenceDocs:
+  htmlTemplate: ./docs/index.html
+  theme:
+    colors:
+      primary:
+        main: "#32329f"

Makefile

@@ -40,6 +40,11 @@ clean: ## Remove previous build.
 	find . -type f -name '*.gen.go' -exec rm {} +
 	git checkout go.mod
 
+.PHONY: docs
+docs: ## Generate documentation.
+	npx @redocly/cli build-docs api/api.yml 
+	mv redoc-static.html public/index.html
+
 .PHONY: help
 help: ## Display this help screen.
 	@grep -E '^[a-z.A-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

api/api.yml

@@ -3,6 +3,7 @@ openapi: 3.0.1
 
 info:
   title: Knox
+  version: 1.0.0
   description:
 
 servers:
@@ -14,6 +15,7 @@ paths:
       tags:
         - Liveness
       summary: Get system health status
+      operationId: getHealth
       responses:
         "200":
           description: System is healthy
@@ -33,6 +35,7 @@ paths:
       tags:
         - Readiness
       summary: Get system readiness
+      operationId: getReady
       responses:
         "200":
           description: System is ready to accept traffic
@@ -192,6 +195,7 @@ paths:
       tags:
         - Users
       summary: Get a list of users
+      operationId: getUsers
       security:
         - api_key: []
       parameters:
@@ -255,6 +259,7 @@ paths:
       tags:
         - Users
       summary: Get a user
+      operationId: getUser
       security:
         - api_key: []
       parameters:
@@ -287,6 +292,7 @@ paths:
       tags:
         - Users
       summary: Update a user
+      operationId: updateUser
       security:
         - api_key: []
       parameters:
@@ -324,6 +330,7 @@ paths:
       tags:
         - Users
       summary: Delete a user
+      operationId: deleteUser
       security:
         - api_key: []
       parameters:
@@ -424,6 +431,7 @@ paths:
       tags:
         - Teams
       summary: Get a team
+      operationId: getTeam
       security:
         - api_key: []
       parameters:
@@ -547,6 +555,7 @@ paths:
       tags:
         - Projects
       summary: Get a list of projects
+      operationId: getProjects
       security:
         - api_key: []
       parameters:
@@ -593,6 +602,7 @@ paths:
       tags:
         - Projects
       summary: Get a project
+      operationId: getProject
       security:
         - api_key: []
       parameters:
@@ -625,6 +635,7 @@ paths:
       tags:
         - Projects
       summary: Update a project
+      operationId: updateProject
       security:
         - api_key: []
       parameters:
@@ -662,6 +673,7 @@ paths:
       tags:
         - Projects
       summary: Delete a project
+      operationId: deleteProject
       security:
         - api_key: []
       parameters:
@@ -722,6 +734,7 @@ paths:
       tags:
         - Environments
       summary: Get a list of environments
+      operationId: getEnvironments
       security:
         - api_key: []
       parameters:
@@ -773,6 +786,7 @@ paths:
       tags:
         - Environments
       summary: Get an environment
+      operationId: getEnvironment
       security:
         - api_key: []
       parameters:
@@ -810,6 +824,7 @@ paths:
       tags:
         - Environments
       summary: Update an environment
+      operationId: updateEnvironment
       security:
         - api_key: []
       parameters:
@@ -852,6 +867,7 @@ paths:
       tags:
         - Environments
       summary: Delete an environment
+      operationId: deleteEnvironment
       security:
         - api_key: []
       parameters:
@@ -912,6 +928,7 @@ paths:
       tags:
         - Snapshots
       summary: Get a list of snapshots
+      operationId: getSnapshots
       security:
         - api_key: []
       parameters:
@@ -958,6 +975,7 @@ paths:
       tags:
         - Snapshots
       summary: Get a snapshot
+      operationId: getSnapshot
       security:
         - api_key: []
       parameters:
@@ -990,6 +1008,7 @@ paths:
       tags:
         - Snapshots
       summary: Update a snapshot
+      operationId: updateSnapshot
       security:
         - api_key: []
       parameters:
@@ -1027,6 +1046,7 @@ paths:
       tags:
         - Snapshots
       summary: Delete a snapshot
+      operationId: deleteSnapshot
       security:
         - api_key: []
       parameters:
@@ -1056,6 +1076,7 @@ paths:
       tags:
         - Tasks
       summary: Get a task
+      operationId: getTask
       security:
         - api_key: []
       parameters:

docs/index.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>API Reference | ReDoc</title>
+    <!-- needed for adaptive design -->
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="icon" type="image/png" href="favicon.png">
+
+    <!--
+    ReDoc uses font options from the parent element
+    So override default browser styles
+    -->
+    <style>
+        body {
+            margin: 0;
+            padding: 0;
+        }
+    </style>
+    {{{redocHead}}}
+</head>
+
+<body>
+    {{{redocHTML}}}
+</body>
+
+</html>