Merge pull request #10 from CubicrootXYZ/openapi

add workflow for rendering OpenAPI 2 specs with redoc

.github/workflows/openapi2_render.yaml

@@ -0,0 +1,39 @@
+on: 
+  workflow_call:
+    inputs:
+      spec_artifact_name:
+        required: true
+        type: string
+      spec_artifact_path:
+        required: true
+        type: string
+      spec_filename:
+        required: true
+        type: string
+
+jobs:
+  render_with_redoc:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.ref, 'refs/tags/')"
+    container:
+      image: cubicrootxyz/golang-ci:v1.23.0
+      options: --user root
+    steps:
+      - uses: actions/download-artifact@master
+        with:
+          name: ${{ inputs.spec_artifact_name }}
+          path: ${{ inputs.spec_artifact_path }}
+      - name: Make docs folder
+        run: mkdir -p docs
+      - name: Convert to OpenApi 3
+        run: openapi-code-sample-generator convert --file ${{ inputs.spec_artifact_path }}${{ inputs.spec_filename }} --output-file docs/openapi3_spec.yaml
+      - name: Add code samples to api documentation
+        run: openapi-code-sample-generator generate --input-file docs/openapi3_spec.yaml --output-file docs/enriched_openapi3_spec.yaml
+      - name: Build static html
+        run: npx redoc-cli bundle docs/enriched_openapi3_spec.yaml --output index.html
+      - name: Archive rendered HTML
+        uses: actions/upload-artifact@v4
+        with:
+          name: rendered-api-docu
+          path: |
+            index.html

.github/workflows/openapi2_render_test.yaml

@@ -0,0 +1,20 @@
+on: push
+
+jobs:
+  openapi2_render_test_prep:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v3
+      - uses: actions/upload-artifact@master
+        with:
+          name: spec
+          path: tests/openapi2/
+  openapi2_render_test:
+    needs: 
+      - openapi2_render_test_prep
+    uses: ./.github/workflows/openapi2_render.yaml
+    with:
+      spec_artifact_name: spec
+      spec_artifact_path: tests/openapi2/
+      spec_filename: petstore.yaml

README.md

@@ -64,4 +64,20 @@ jobs:
     uses: CubicrootXYZ/Workflows/.github/workflows/[email protected]
     with:
       workdir: "tests/jinja/"
+```
+
+## OpenAPI
+
+### Render OpenAPI 2 specs with redoc
+
+Render an OpenAPI 2 spec with `redoc`. The spec file needs to be present in the given artifact. The rendered `index.html` will be added to the artifact `rendered-api-docu`.
+
+```yaml
+jobs:
+  render:
+    uses: CubicrootXYZ/Workflows/.github/workflows/openapi2_render.yaml
+    with:
+      spec_artifact_name: spec
+      spec_artifact_path: tests/openapi2/
+      spec_filename: petstore.yaml
 ```

tests/openapi2/README.md

@@ -0,0 +1 @@
+Petstore is licensed under [Apache](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE).

tests/openapi2/petstore.yaml

@@ -0,0 +1,142 @@
+swagger: "2.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification
+  termsOfService: http://swagger.io/terms/
+  contact:
+    name: Swagger API Team
+    email: [email protected]
+    url: http://swagger.io
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+host: petstore.swagger.io
+basePath: /api
+schemes:
+  - http
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  /pets:
+    get:
+      description: |
+        Returns all pets from the system that the user has access to
+      operationId: findPets
+      parameters:
+        - name: tags
+          in: query
+          description: tags to filter by
+          required: false
+          type: array
+          collectionFormat: csv
+          items:
+            type: string
+        - name: limit
+          in: query
+          description: maximum number of results to return
+          required: false
+          type: integer
+          format: int32
+      responses:
+        "200":
+          description: pet response
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Pet'
+        default:
+          description: unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+    post:
+      description: Creates a new pet in the store.  Duplicates are allowed
+      operationId: addPet
+      parameters:
+        - name: pet
+          in: body
+          description: Pet to add to the store
+          required: true
+          schema:
+            $ref: '#/definitions/NewPet'
+      responses:
+        "200":
+          description: pet response
+          schema:
+            $ref: '#/definitions/Pet'
+        default:
+          description: unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+  /pets/{id}:
+    get:
+      description: Returns a user based on a single ID, if the user does not have access to the pet
+      operationId: find pet by id
+      parameters:
+        - name: id
+          in: path
+          description: ID of pet to fetch
+          required: true
+          type: integer
+          format: int64
+      responses:
+        "200":
+          description: pet response
+          schema:
+            $ref: '#/definitions/Pet'
+        default:
+          description: unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+    delete:
+      description: deletes a single pet based on the ID supplied
+      operationId: deletePet
+      parameters:
+        - name: id
+          in: path
+          description: ID of pet to delete
+          required: true
+          type: integer
+          format: int64
+      responses:
+        "204":
+          description: pet deleted
+        default:
+          description: unexpected error
+          schema:
+            $ref: '#/definitions/Error'
+definitions:
+  Pet:
+    allOf:
+      - $ref: '#/definitions/NewPet'
+      - required:
+        - id
+        type: "object"
+        properties:
+          id:
+            type: integer
+            format: int64
+
+  NewPet:
+    type: "object"
+    required:
+      - name  
+    properties:
+      name:
+        type: string
+      tag:
+        type: string    
+
+  Error:
+    type: "object"
+    required:
+      - code
+      - message
+    properties:
+      code:
+        type: integer
+        format: int32
+      message:
+        type: string