Host OpenAPI Documentation with Github Pages

3 min readOct 12, 2020

You have written or generated your OpenAPI Documentation and you want to publish it to share it with your team or the world?

We will be using an HTML page where we integrate the Swagger UI over a CDN, and load our openapi.yaml, for this example I will use the Petstore Documentation and we will be publishing it on Github Pages. The steps to publishing it to another Provider might be similar.

First, we fill our index.html file:

<!DOCTYPE html>
<html lang=”en”>
<head>
<meta charset=”UTF-8">
<meta name=”viewport” content=”width=device-width, initial-scale=1">
<link rel=”stylesheet” type=”text/css” href=”//pagecdn.io/lib/swagger-ui/v3.31.1/swagger-ui.css”>
<title>OpenAPI Petstore</title>
<body><div id=”openapi”><script src=”//pagecdn.io/lib/swagger-ui/v3.31.1/swagger-ui-bundle.js”></script>
<script>
window.onload = function () {
  const ui = SwaggerUIBundle({
    url: “openapi.yaml”,
    dom_id: “#openapi”
  })
}
</script>
</body>

We load the CSS and JS for the Swagger UI and we initialize the SwaggerUIBundle with a small config object that links to our openapi.yaml file that’s right beside our HTML page and configure we want to load it into the DOM tag with id #openapi.

Besides the index.html file we save our openapi.yaml file with the following content (you might want to use your own definitions):

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
  description: |
    ## Petstore API

    | Syntax | Description |
    | ----------- | ----------- |
    | Header | Title |
    | Paragraph | Text | 

servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

Then, we need to create a GitHub repository with the name *.github.io, I use openapi-petstore-ui.github.io

Then, we open up the command line and switch into the folder, where we create the index.html and openapi.yaml and run the following commands:

git init
git add --a
git commit -m "first commit"
git remote add origin git@github.com:pguso/openapi-petstore-ui.github.io.git
git push --set-upstream origin master

That’s it now is your documentation available. You can check the URL of your page if you go into the repository settings to the section Github Pages, there you find the URL after “Your site is ready to be published”.

The GitHub Page to this story is available here https://pguso.github.io/openapi-petstore-ui.github.io/

Host OpenAPI Documentation with Github Pages

Written by Patric