Maintaining the latest API documents is often the biggest point of pain for developers and teams. Often, the speculation of the API changes but the documents are left behind, leaving the developers with old or contradictory information. It disappoints your API users and adds to support overhead.
This is the place where automation comes. By combining the features of Open PI with Gut Hub Actions, you can make sure that your documents are always compatible with your API changes.
Openi Works as a single reference point for your API design, keeping your documents permanent, accurate, and connected with your API.
Gut Hub Actions The workflows automatically, confirm its speculation, builds documents, and publishes gut hub pages in seconds.
This tutorial runs through a practical example of how to use Gut Hub actions to update your documents.
The table of content
Provisions
How to configure your repository
If you don’t already have one, make a gut hub repository. For this tutorial, I will use api-docs Name as a repo.
Then open the VScode and make a folder with the same name.
How to make Open PI details
You just made a folder inside the folder you just said spec And add a file greetings.yaml With the following content:
openapi: 3.0.3
info:
title: Greetings API
version: 1.0.0
description: This is a greetings API demonstrating a simple greeting endpoint with query parameters and multilingual support.
license:
name: MIT
url:
servers:
- url:
description: Production server(v1)
- url:
description: Staging server(v1)
security:
- api_key: ()
paths:
/hello:
get:
summary: Returns a greeting
operationId: getGreeting
parameters:
- name: name
in: query
required: false
description: Name of the person to greet
schema:
type: string
example: Ezinne
- name: lang
in: query
required: false
description: Language of the greeting (default is English)
schema:
type: string
enum: (en, fr, es, ig)
example: en
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
english:
value: { message: "Hello, Ezinne!" }
french:
value: { message: "Bonjour, Ezinne!" }
spanish:
value: { message: "¡Hola, Ezinne!" }
igbo:
value: { message: "Ndeewo, Ezinne!" }
components:
securitySchemes:
api_key:
type: apiKey
name: Authorization
in: header
This is a simple special special with multi -linguistic congratulations. As your API grows (say more languages or versions), it can be painful to keep the documents manually harmonious. That’s why automation helps.
How to test the API test locally
Install Tolls:
Before setting gut hub actions, you can test API locally on your machine by sorting redocly (Redoc was called) and is examining it in the HTML environment.
Redukley is a lightweight, customized tool to present open PPI sunglasses as an interactive HTML document. It is ideal for the deployment of a stable site that makes it ideal for this scenario.
The HTTP server is a local server before you press the gut hub and deploy the gut hub on the pages you can use to test the DOC on your machine.
Create a landing page:
In your project, make a docs Folder and add index.html:
html>
<html>
<head>
<title>API Documentationtitle>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
head>
<body>
<redoc spec-url="../spec/greetings.yaml">redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">script>
body>
html>
Confirm your speculation:
redocly lint spec/greetings.yaml
If there is no errors or alert you should see it:
Woohoo! Your API description is valid. 🎉
Note: It is important to confirm your API speculation before testing as it will flag any possible mistakes. The reason for this is that if you have any mistakes in your speculation, you will fail to run again.
Preview in the browser:
Drive http-serverAnd you should see it in the terminal:
Starting up http-server, serving ./
Available on:
http://127.0.0.1:8080
http://192.168.x.x:8080
Hit CTRL-C to stop the server
Open / And navigate /docs To see your documents.
How to push local changes into the gut hub
After making local changes, you need to set the API document so that whenever you make changes, it can be automatically updated.
If you are emphasizing storage for the first time, run these commands:
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin -repo-url>
git push -u origin main
How to compose your Gut Hub Action Workflow
You can set up your gut hubwork flu by making some folders.
First, create .github/workflows/ I api-docs Folder then, inside workflows Folder, make a docs.yml. This is a workflow file that will work as a stimulus to operate the verification, manufacture the HTML with Redocali, and deploy in the botanical pages at the same time.
name: Build API Documentation and Deploy to GitHub Pages
on:
push:
branches:
- main
paths:
- 'spec/greetings.yaml'
jobs:
build-spec:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Redocly CLI
run: npm install -g @redocly/cli
- name: Validate OpenAPI Spec
run: redocly lint spec/greetings.yaml
- name: Create build directory
run: mkdir -p public
- name: Copy spec
run: mkdir -p public/spec && cp spec/greetings.yaml public/spec/
- name: Copy landing page
run: cp docs/index.html public/index.html
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
What is happening in this code is here:
Moves when changes are pushed
mainAffects itspec/greetings.yaml.Check the repo code.
Node Dot Jet sets up and installs Redocali.
Confirmation of your Openpe Specity (so broken species will not be deployed).
Copies the Special and Index Page A
public/FolderDeploy
public/togh-pagesBranch with gut hub pages.
Since we are working with a local test, update the file route index.html:
html>
<html>
<head>
<title>API Documentationtitle>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
head>
<body>
<redoc spec-url="./spec/greetings.yaml">redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">script>
body>
html>
It is so public The directory in the workflow will be able to access it properly.
This workflow will be operated only when he detects changes to the establishment of API (greetings.yml) To see the workflow practically, make a minor modification greetings.yaml.
Pushes the changes into your gut hub reservoir:
git add .
git commit -m 'add changes'
git push
How to configure Gut Hub Pages
What are the gut hub pages?
Gut hub pages There is a hosting platform owned by a gut hub where you can host the websites directly from your gut hub account. This means that you can post static sites on the Internet using the Gut Hub Domain and anyone with the website link can access it.
There are other hosting platforms you can use to deploy static websites such as Net Leaf And Vercel. But for these documents, gut hub pages are used on the same platform because it is easy to set up.
Got hub pages to compile
Click on the settings tab in your reservoir and set the gut hub pages.
Under the Source, Select:
Then save and wait for the workflow to finish.
Your documents will be directly: https://.
How to handle more than one version
If you have multiple API version to update what will happen? Let’s suppose that this tutorial included more features in different versions in the simple congratulations API. In this case, you can manage APIS for different versions in the same page and automatically build and deploy it.
About the version
Version 1 (v1)
This is the starting point that is greetings.yaml. API has only one /hello The closing point that returns the greeting in four languages (English, French, Spanish, or Egbo).
Version 2 (V2)
In version 2, the API adds the features of creation and reading. You can do:
Version 3 (V3)
Version 3 builds a updated functionality in the upper part of the V2. With and recovering congratulations, you can now update using the current congratulations PUT /hello/{id}.
How to configure the version locally
First, make a v1 Folder and move greetings.yaml File in it. Since we are going to use the version, you can delete the current spec Folder
Again, make a v2 Folder and make A greetings-v2.yaml File Greeting API for Version 2 Get Here.
Next, make a v3 Folder and add greetings-v3.yaml File Get API Here for Version 3.
To follow the same style with others, change version 1 file name greetings-v1.yaml. Then refresh you index.html To adjust the other two versions.
html>
<html>
<head>
<title>API Documentationtitle>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body {
font-family: Arial, sans-serif;
margin: 0;
}
header {
background: #2c3e50;
color: white;
padding: 1rem;
display: flex;
justify-content: space-between;
align-items: center;
}
select {
padding: 0.4rem;
font-size: 1rem;
}
style>
head>
<body>
<header>
<h2>API Documentationh2>
<div>
<label for="version">Version: label>
<select id="version" onchange="loadSpec()">
<option value="./v1/greetings-v1.yaml">v1option>
<option value="./v2/greetings-v2.yaml">v2option>
<option value="./v3/greetings-v3.yaml">v3option>
select>
div>
header>
<div id="redoc-container">div>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">script>
<script>
function loadSpec() {
const version = document.getElementById("version").value;
Redoc.init(version, {}, document.getElementById("redoc-container"));
}
window.onload = loadSpec;
script>
body>
html>
How to verify API SPECIAL
Prior to this article, I mentioned your details locally. Now that you have two more versions of the API greetings, run the test to highlight and fix any existing errors.
How to update the Gut Hub Action Workflow
Now that you have three API specific versions, you need to update your workflow to monitor three specific files and HTML document for changes, and then press and deploy it in the bothered pages.
Add it to your own .github/workflows/docs.yml:
name: Build and Deploy API Documentation
on:
push:
branches: ( main )
paths:
- 'docs/index.html'
- 'v1/greetings-v1.yaml'
- 'v2/greetings-v2.yaml'
- 'v3/greetings-v3.yaml'
jobs:
build-and-deploy:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Create build directory
run: mkdir -p public
- name: Copy v1 spec
run: mkdir -p public/v1 && cp v1/greetings-v1.yaml public/v1/
- name: Copy v2 spec
run: mkdir -p public/v2 && cp v2/greetings-v2.yaml public/v2/
- name: Copy v3 spec
run: mkdir -p public/v3 && cp v3/greetings-v3.yaml public/v3/
- name: Copy landing page
run: cp docs/index.html public/index.html
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
And finally, press the changes and reload the site. It should feature the latest documents.
Abstract
In this tutorial, you have learned how to update your API documents. We started with a single Openi Specke and a basic HTML page that Redukli presented, and tested it locally. After that we automatically compiled the gut hubs to verify this speculation, copy the files and deploy the documents to the gut hub pages. Finally, we extended the setup to handle a multiple API version in one place.
With this workflow, your documents are accurate, latest and harassed, so when you move the changes, you are directly changing your API speculation.