publish api docs to github pages

.github/workflows/lint.yml

@@ -32,10 +32,10 @@ jobs:
         go mod tidy
         git diff --exit-code
 
-  api:
+  apidocs:
     runs-on: ubuntu-20.04
 
     steps:
     - uses: actions/checkout@v2
 
-    - run: make api-lint
+    - run: make apidocs-lint

.github/workflows/release.yml

@@ -51,3 +51,18 @@ jobs:
       env:
         DOCKER_USER: ${{ secrets.DOCKER_USER }}
         DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+
+  apidocs:
+    runs-on: ubuntu-20.04
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - run: make apidocs-gen
+
+    - run: mv apidocs/*.html apidocs/index.html
+
+    - uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./apidocs

.gitignore

@@ -1,3 +1,4 @@
 /tmp
 /release
 /coverage*.txt
+/apidocs/*.html

Makefile

@@ -17,7 +17,8 @@ help:
 	@echo "  lint           run linters"
 	@echo "  bench NAME=n   run bench environment"
 	@echo "  run            run app"
-	@echo "  api-lint"      run api linters"
+	@echo "  apidocs-lint   run api docs linters"
+	@echo "  apidocs-gen    generate HTML from api docs"
 	@echo "  release        build release assets"
 	@echo "  dockerhub      build and push docker hub images"
 	@echo ""
@@ -155,14 +156,14 @@ run:
 	temp \
 	sh -c "/out"
 
-define DOCKERFILE_API_LINT
+define DOCKERFILE_APIDOCS_LINT
 FROM $(NODE_IMAGE)
 RUN yarn global add @redocly/openapi-cli@1.0.0-beta.54
 endef
-export DOCKERFILE_API_LINT
+export DOCKERFILE_APIDOCS_LINT
 
-api-lint:
-	echo "$$DOCKERFILE_API_LINT" | docker build . -f - -t temp
+apidocs-lint:
+	echo "$$DOCKERFILE_APIDOCS_LINT" | docker build . -f - -t temp
 	docker run --rm -v $(PWD)/apidocs:/s -w /s temp \
 	sh -c "openapi lint openapi.yaml"
 
@@ -177,6 +178,17 @@ RUN make release-nodocker
 endef
 export DOCKERFILE_RELEASE
 
+define DOCKERFILE_APIDOCS_GEN
+FROM $(NODE_IMAGE)
+RUN yarn global add redoc-cli@0.12.2
+endef
+export DOCKERFILE_APIDOCS_GEN
+
+apidocs-gen:
+	echo "$$DOCKERFILE_APIDOCS_GEN" | docker build . -f - -t temp
+	docker run --rm -v $(PWD)/apidocs:/s -w /s temp \
+	sh -c "redoc-cli bundle openapi.yaml"
+
 release:
 	echo "$$DOCKERFILE_RELEASE" | docker build . -f - -t temp
 	docker run --rm -v $(PWD):/out \

apidocs/.redocly.yaml

@@ -1,3 +0,0 @@
-lint:
-  extends:
-    - recommended

apidocs/openapi.yaml

@@ -181,40 +181,60 @@ components:
           $ref: '#/components/schemas/PathConf'
         source:
           oneOf:
-          - type: object
-            properties:
-              type:
-                type: string
-                enum: ['rtspsession']
-              id:
-                type: string
-          - type: object
-            properties:
-              type:
-                type: string
-                enum: ['rtmpconn']
-              id:
-                type: string
+          - $ref: '#/components/schemas/PathSourceRTSPSession'
+          - $ref: '#/components/schemas/PathSourceRTMPConn'
         sourceReady:
           type: boolean
         readers:
           type: array
           items:
             oneOf:
-            - type: object
-              properties:
-                type:
-                  type: string
-                  enum: ['rtspsession']
-                id:
-                  type: string
-            - type: object
-              properties:
-                type:
-                  type: string
-                  enum: ['rtmpconn']
-                id:
-                  type: string
+            - $ref: '#/components/schemas/PathReaderRTSPSession'
+            - $ref: '#/components/schemas/PathReaderRTMPConn'
+            - $ref: '#/components/schemas/PathReaderHLSMuxer'
+
+    PathSourceRTSPSession:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [rtspsession]
+        id:
+          type: string
+
+    PathSourceRTMPConn:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [rtmpconn]
+        id:
+          type: string
+
+    PathReaderRTSPSession:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [rtspsession]
+        id:
+          type: string
+
+    PathReaderRTMPConn:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [rtmpconn]
+        id:
+          type: string
+
+    PathReaderHLSMuxer:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [hlsmuxer]
 
     RTSPSession:
       type: object
@@ -248,6 +268,13 @@ paths:
     post:
       operationId: configSet
       summary: changes the current configuration.
+      description: all fields are optional.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Conf'
       responses:
         '200':
           description: the request was successful.
@@ -260,7 +287,7 @@ paths:
     post:
       operationId: configPathsAdd
       summary: adds the configuration of a path.
-      description: ''
+      description: all fields are optional.
       parameters:
       - name: name
         in: path
@@ -268,6 +295,12 @@ paths:
         description: the name of the path.
         schema:
           type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PathConf'
       responses:
         '200':
           description: the request was successful.
@@ -280,7 +313,7 @@ paths:
     post:
       operationId: configPathsEdit
       summary: changes the configuration of a path.
-      description: ''
+      description: all fields are optional.
       parameters:
       - name: name
         in: path
@@ -288,6 +321,12 @@ paths:
         description: the name of the path.
         schema:
           type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PathConf'
       responses:
         '200':
           description: the request was successful.