Host OpenAPI Documentation with Github Pages

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, 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.

Beside the index.html file we save our openapi.yaml file with 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 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 at”.

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