Automated API docs with multiple API version support

Changelog

• Add support for generating/maintaining API docs for multiple API versions which may be spread across separate Git branches
• [BREAKING CHANGE] Overhaul inputs and internal scripts to transition to consuming a JSON array supporting multiple API spec configs, rather than a single filepath

Example v1 usage (only supports a single OpenAPI spec):

name: Generate API docs and deploy to GitHub Pages
on:
  # Automatically trigger when push to main branch
  push:
    branches: ["main"]
  # Enable running workflow manually from GitHub Actions
  workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  generate-api-docs:
    name: Generate API Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Generate API docs and deploy to GitHub Pages
        uses: msayson/openapi-github-pages-action@v1.0.0
        with:
          openapi-json-filepath: openapi/ConsentManagementApi.openapi.json
          api-docs-filepath: v1/docs.html

Example v2 usage (supports multiple OpenAPI specs):

name: Generate API docs and deploy to GitHub Pages
on:
  # Automatically trigger when push to any branch
  push:
  # Enable running workflow manually from GitHub Actions
  workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  generate-api-docs:
    name: Generate API Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Generate API docs and deploy to GitHub Pages
        uses: msayson/openapi-github-pages-action@v1.0.0
        with:
          api-configs: |-
            [
              {
                "branch": "main",
                "openapi-json-filepath": "openapi/ConsentManagementApi.openapi.json",
                "api-doc-filepath": "latest/docs.html"
              },
              {
                "branch": "v1",
                "openapi-json-filepath": "openapi/ConsentManagementApi.openapi.json",
                "api-doc-filepath": "v1/docs.html"
              },
              {
                "branch": "v2",
                "openapi-json-filepath": "openapi/ConsentManagementApi.openapi.json",
                "api-doc-filepath": "v2/docs.html"
              }
            ]
          api-docs-dir: docs

Full Changelog: v1.0.0...v2.0.0

Automated API docs for a single OpenAPI spec file

Summary

This GitHub Action encapsulates workflow logic to:

• Convert a provided OpenAPI JSON spec to YAML which is the required format for ReDoc
• Generate ReDoc API documentation in HTML format
• Deploy the API documentation to the client repository's GitHub Pages