diff --git a/.github/workflows/openapi2_render.yaml b/.github/workflows/openapi2_render.yaml new file mode 100644 index 0000000..46a7650 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/openapi2_render_test.yaml b/.github/workflows/openapi2_render_test.yaml new file mode 100644 index 0000000..a568cf7 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index dabfb60..a11da6d 100644 --- a/README.md +++ b/README.md @@ -64,4 +64,20 @@ jobs: uses: CubicrootXYZ/Workflows/.github/workflows/jinja.yaml@v1.0.0 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 ``` \ No newline at end of file diff --git a/tests/openapi2/README.md b/tests/openapi2/README.md new file mode 100644 index 0000000..6975741 --- /dev/null +++ b/tests/openapi2/README.md @@ -0,0 +1 @@ +Petstore is licensed under [Apache](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE). \ No newline at end of file diff --git a/tests/openapi2/petstore.yaml b/tests/openapi2/petstore.yaml new file mode 100644 index 0000000..2cff013 --- /dev/null +++ b/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: apiteam@swagger.io + 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 \ No newline at end of file