Diverse Examples of Using GitHub Pages for API Docs

Explore practical examples of using GitHub Pages for effective API documentation.
By Jamie

Introduction

GitHub Pages is a powerful tool for hosting static websites directly from a GitHub repository. It can be particularly useful for creating and maintaining API documentation due to its simplicity, version control, and easy integration with Markdown. Below are three diverse examples of using GitHub Pages for API documentation.

Example 1: Simple REST API Documentation

Context

This example showcases how to create straightforward documentation for a RESTful API that allows users to access and manipulate data related to books.

To start, create a new GitHub repository and enable GitHub Pages in the repository settings. Then, add a README.md file that outlines the API endpoints.

Example

# Book API Documentation

## Base URL
`https://api.example.com/v1`

## Endpoints

### Get All Books

- **Method**: `GET`
- **Endpoint**: `/books`
- **Description**: Retrieves a list of all books.
- **Response**:
  ```json
  [
    {
      "id": 1,
      "title": "1984",
      "author": "George Orwell"
    },
    {
      "id": 2,
      "title": "To Kill a Mockingbird",
      "author": "Harper Lee"
    }
  ]

Get Book By ID

  • Method: GET
  • Endpoint: /books/{id}
  • Description: Retrieves a single book by its ID.

  • Response:

    {
  "id": 1,
  "title": "1984",
  "author": "George Orwell"
}


### Notes
Using GitHub Pages for this API documentation allows for easy updates and collaboration with team members. Consider adding additional Markdown files for detailed explanations of each endpoint, error handling, and usage examples.

## Example 2: Interactive API Documentation with Swagger

### Context
In this example, we demonstrate how to integrate Swagger UI into GitHub Pages to provide interactive API documentation. This is suitable for APIs that require a more detailed and interactive experience for users.

### Example
1. Set up your GitHub Pages repository.
2. Include the Swagger UI files in your project.
3. Create an `index.html` file that references your Swagger JSON file.

```html
<!DOCTYPE html>
<html>
<head>
    <title>API Documentation</title>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.51.1/swagger-ui.css" />
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.51.1/swagger-ui-bundle.js"></script>
    <script>
        const ui = SwaggerUIBundle({
            url: "https://api.example.com/swagger.json",
            dom_id: '#swagger-ui',
            presets: [SwaggerUIStandalonePreset],
            layout: "StandaloneLayout"
        });
    </script>
</body>
</html>

Notes

This setup allows users to interact with the API directly from the documentation, providing them with a hands-on experience. Make sure to keep your Swagger JSON file updated to reflect any changes in your API.

Example 3: Versioned Documentation for an Evolving API

Context

For APIs that undergo frequent changes, maintaining versioned documentation is crucial. This example illustrates how to organize your GitHub Pages site to support multiple versions of your API documentation.

Example

  1. Create a repository structure like this:
/docs
    /v1
        README.md
    /v2
        README.md
/index.html
  1. In your index.html, provide links to each version:
<!DOCTYPE html>
<html>
<head>
    <title>API Documentation</title>
</head>
<body>
    <h1>API Documentation</h1>
    <h2>Versions</h2>
    <ul>
        <li><a href="/docs/v1/README.md">Version 1</a></li>
        <li><a href="/docs/v2/README.md">Version 2</a></li>
    </ul>
</body>
</html>

Notes

Each version’s README.md can include specific features, endpoints, and any deprecation notices. This method provides clarity to users about which version of the API they are using and helps them navigate changes more effectively.

These examples illustrate the versatility of GitHub Pages for hosting API documentation. By leveraging GitHub’s features, you can create maintainable, interactive, and versioned documentation that enhances the user experience.