Automating API Documentation Generation with OpenAPI and GitHub Actions

Introduction#

Maintaining accurate and up-to-date API documentation is crucial for developers using your services. However, manually updating documentation can be time-consuming and prone to errors, especially with frequent API changes. This article explores how to automate the generation and deployment of API documentation using OpenAPI specifications and GitHub Actions. This approach ensures that your documentation remains synchronized with your API development, improving developer experience and reducing integration issues.

Understanding OpenAPI (Swagger)#

OpenAPI, formerly known as Swagger, is a standard, language-agnostic interface for describing RESTful APIs. An OpenAPI specification allows both humans and computers to understand the capabilities of an API without requiring access to source code, documentation, or network traffic inspection. It defines endpoints, request/response formats, authentication methods, and other essential details.

The OpenAPI specification is typically written in YAML or JSON format. Here’s a simplified example:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

This snippet defines a simple API endpoint /users that returns a list of users. Tools can then use this specification to generate documentation, client SDKs, and even server stubs.

Choosing an OpenAPI Toolchain#

Several tools can generate API documentation from OpenAPI specifications. Some popular choices include:

Swagger UI: A widely used, interactive UI for visualizing OpenAPI specifications. It renders the specification in a user-friendly format, allowing developers to explore the API and even make test requests.
Redoc: Another popular documentation generator that focuses on a clean, readable, and customizable documentation experience. It’s particularly well-suited for complex APIs.
Stoplight: A comprehensive API design platform that includes tools for creating, documenting, and testing APIs.

For this article, we’ll focus on using Swagger UI due to its simplicity and widespread adoption. We’ll leverage a Docker image of Swagger UI to serve the generated documentation.

Setting up a GitHub Repository#

First, create a GitHub repository to store your API specification and documentation. This repository will also host the GitHub Actions workflow.

Create a new repository: On GitHub, click the ”+” button and select “New repository”.
Add your OpenAPI specification: Place your OpenAPI specification file (e.g., openapi.yaml or openapi.json) in the root of the repository.
(Optional) Create a docs directory: You can optionally create a docs directory to store the generated documentation files.

Creating a GitHub Actions Workflow#

Now, we’ll create a GitHub Actions workflow to automate the documentation generation and deployment process. This workflow will:

Checkout the repository.
Generate the Swagger UI HTML file.
Deploy the documentation to GitHub Pages (or another hosting solution).

Create a new file named .github/workflows/deploy-docs.yml in your repository. Here’s an example workflow configuration:

name: Deploy API Documentation

on:
  push:
    branches:
      - main # Or your main branch name

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Generate Swagger UI
        run: |
          docker run --rm -v $(pwd):/app swaggerapi/swagger-ui:v4.19.0 -u /app/openapi.yaml -o /app/docs

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v3

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./docs

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Explanation:

name: Deploy API Documentation: Defines the name of the workflow.
on: push: Triggers the workflow on every push to the main branch. You can adjust the branches filter to match your development workflow.
jobs: deploy: Defines a job named deploy that will run on an Ubuntu virtual machine.
actions/checkout@v3: Checks out the repository code.
docker run ...: This step uses a Docker container to run Swagger UI.
- swaggerapi/swagger-ui:v4.19.0: Specifies the Docker image to use. You can find the latest version on Docker Hub.
- -v $(pwd):/app: Mounts the current directory (repository root) to the /app directory inside the container.
- -u /app/openapi.yaml: Specifies the location of the OpenAPI specification file within the container. Adjust this if your file is named differently or located in a different directory.
- -o /app/docs: Specifies the output directory for the generated documentation. This will create a docs directory in your repository.
actions/configure-pages@v3: Configures GitHub Pages for deployment.
actions/upload-pages-artifact@v2: Uploads the generated documentation to GitHub Pages.
actions/deploy-pages@v2: Deploys the documentation to GitHub Pages.

Important Considerations:

Docker: This workflow relies on Docker. Ensure that Docker is installed and configured correctly on your system if you’re testing the workflow locally.
OpenAPI Specification Path: Adjust the -u /app/openapi.yaml argument in the docker run command to match the actual path to your OpenAPI specification file within the repository.
GitHub Pages: This workflow assumes you are deploying to GitHub Pages. Enable GitHub Pages for your repository in the repository settings. You’ll need to specify the docs folder as the source for GitHub Pages.
Error Handling: Consider adding error handling to the workflow to gracefully handle failures, such as invalid OpenAPI specifications or deployment issues.

Committing and Pushing the Changes#

Commit the .github/workflows/deploy-docs.yml file and your OpenAPI specification file to your repository and push the changes to GitHub. This will trigger the GitHub Actions workflow.

Verifying the Deployment#

After the workflow completes successfully, navigate to your GitHub Pages URL (usually https://<your-username>.github.io/<your-repository-name>) to view the generated API documentation. You should see the Swagger UI interface displaying your API documentation.

Customization and Enhancements#

This is a basic example, and you can customize it further to suit your specific needs:

Custom Themes: Swagger UI and Redoc support custom themes to match your branding. You can configure the Docker image to use a custom theme file.
Authentication: If your API requires authentication, you can configure Swagger UI to handle authentication tokens or API keys.
Automated Testing: Integrate automated API testing into the workflow to ensure that your API is working as expected.
Alternative Hosting: Instead of GitHub Pages, you can deploy the documentation to other hosting platforms like Netlify, Vercel, or AWS S3.
Branching Strategy: Adapt the workflow to your branching strategy. For example, you might want to generate documentation for feature branches and deploy them to separate environments.
Redoc Integration: Replace the Swagger UI docker image with a Redoc docker image for a different documentation style.

Conclusion#

Automating API documentation generation with OpenAPI and GitHub Actions significantly simplifies the documentation process and ensures that your documentation remains synchronized with your API development. By leveraging these tools, you can improve developer experience, reduce integration issues, and focus on building great APIs. This approach promotes a documentation-as-code mindset, where documentation is treated as an integral part of the development lifecycle.