openapi-github-pages-action

GitHub Action to generate and deploy API documentation to GitHub Pages, using OpenAPI specification files as input.

By default, API docs are generated at username.github.io/repository-name/provided-api-doc-filepath.

If you've set up a GitHub Pages custom domain for your account, that will be used instead of username.github.io.

See example API docs generated by this GitHub Action:

Prerequisites

GitHub Pages requires that source repositories either be public or in supported paid accounts.
The repository must have GitHub Pages enabled with GitHub Actions, by going to "Settings" > "Pages" > "Build and deployment", and under "Source", selecting "GitHub Actions".
The repository must provide a pre-built OpenAPI JSON spec file.

Usage

See action.yml

Add the following permissions to your GitHub workflow, prior to the lines defining workflow jobs.

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

Add the following steps to your GitHub workflow, replacing the input values:

- name: Generate API docs and deploy to GitHub Pages
  uses: msayson/[email protected]
  with:
    # JSON string configs for each OpenAPI spec to document
    # - branch: (Optional) Git branch to fetch spec file from, eg. origin/main
    #           If not provided, assumes file is available from current branch
    # - generate-api-spec-command: (Optional) Command to run to generate spec file
    # - openapi-json-filepath: Filepath of OpenAPI JSON spec
    # - api-doc-filepath: Filepath for generated API doc, within the common directory defined by api-docs-dir
    api-configs: |-
      [
        {
          "branch": "YOUR_BRANCH",
          "openapi-json-filepath": "YOUR_OPENAPI_SPEC_FILEPATH",
          "api-doc-filepath": "YOUR_API_DOC_FILEPATH"
        }
      ]
    # Parent directory to use for generated API docs HTML
    api-docs-dir: 'YOUR_API_DOCS_FILEPATH'

Generate API docs for main branch

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/[email protected]
        with:
          api-configs: |-
            [
              {
                "openapi-json-filepath": "openapi/ConsentManagementApi.openapi.json",
                "api-doc-filepath": "latest/docs.html"
              }
            ]
          api-docs-dir: docs

Generate API docs for multiple releases

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/[email protected]
        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

Technologies

jq is a lightweight and flexible command-line JSON processor.

yq is used to convert JSON to YAML, since YAML is the required format for ReDoc, while many tools such as Smithy generate OpenAPI specs with the JSON format.

ReDoc is used to automatically generate API documentation from the OpenAPI YAML specification.

GitHub Actions are used to automatically generate and deploy HTML API documentation to GitHub Pages.

GitHub CLI is used to retrieve OpenAPI spec files from other Git branches.

msayson / openapi-github-pages-action Goto Github PK