TechnicalPig🐷: Hosting Your OpenAPI Documentation on GitHub Pages

When developing API, clear and accessible documentation is crucial. It facilitates easier integration and adoption by developers.

This article will walk you through a streamlined process to create, generate, and host your OpenAPI documentation on GitHub Pages. We will use:

•  Zod for schema validation,

• zod-to-openapi for schema conversion,

• Redocly for documentation, and

•  gh-pages for easy web hosting.

Step 1: Setting up your project

Create a new directory for your project and initialise a Node.js project. Install the required dependencies by running:

mkdir my-openapi-project
cd my-openapi-project
npm init -y
npm install zod @asteasolutions/zod-to-openapi redocly-cli gh-pages --save-dev

Step 2: Defining your Zod schema

Zod allows you to build schemas with ease. Create a schema.ts file to define your API structure. For instance:

// schema.ts
import { z } from 'zod';

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

export { userSchema };

Read more about Zod here - https://zod.dev/

Step 3: Generating OpenAPI Document with zod-to-openapi

Convert your Zod schema into an OpenAPI specification using zod-to-openapi. You'll need to script this conversion in a file, say convert-to-openapi.ts

// convert-to-openapi.ts
import { generateOpenApi } from '@asteasolutions/zod-to-openapi';
import { userSchema } from './schema';
import fs from 'fs';

const openApiDocument = generateOpenApi({
  title: 'My API',
  version: '1.0.0',
  schemas: { User: userSchema },
});

fs.writeFileSync('openapi.json', JSON.stringify(openApiDocument, null, 2));

Execute the script to produce your openapi.json.

Step 4: Create web-ready documentation with Redocly CLI

After converting your Zod schema to an OpenAPI specification, the next step is to generate static HTML documentation. Redoc is a clean and easy way to produce web-ready documentation from an OpenAPI description.

With Redocly CLI installed, you can generate your API documentation from the OpenAPI specification file (openapi.json). Navigate to your project directory in the terminal, and run the following command:

redocly build-docs openapi.json -o ./docs/index.html

In this command:

• build-docs is the Redocly CLI command used to generate documentation.

• openapi.json is the path to your OpenAPI document.

• The -o option specifies the output location and filename for the generated HTML file. Here, we are directing Redocly CLI to place the generated file in a docs directory under the name index.html. You can adjust the path as needed based on your project's structure.

This process will generate a single HTML file (index.html) that contains all your API documentation. This file is self-contained and can be hosted on any static file server, including GitHub Pages.

Step 5: Deploying to GitHub Pages with gh-pages

After generating your documentation, proceed to deploy it to GitHub Pages to make it accessible to your users. We are going to deploy using the gh-pages package. Add a deployment script to your package.json and execute it to publish your documentation:

"scripts": {
  "deploy": "gh-pages -d ."
}

Next, run:

npm run deploy

Ensure your GitHub repository settings are configured to serve GitHub Pages from the gh-pages branch.

Conclusion

This guide outlines the process of generating and hosting OpenAPI documentation on GitHub Pages. This setup not only ensures your API documentation is always up-to-date but also leverages tools for schema validation, documentation generation, and web hosting!