OpenAPI Hook

Build your API documentation to your exact specifications. openapi-hook takes your OpenAPI specification and turns it into a type-safe object you can use to build your dream documentation site. It’s an alternative to the options out there that offer limited customizability or must be hosted on another site. It’s open source and free to use.

This soon-to-be published NPM module officially supports OAS (OpenAPI Specification) 3.1.x. You may be able to use it with OAS 3.0.x, but may experience issues. If you’d like to use this package, consider upgrading your OpenAPI specification to OAS 3.1.x.

In addition, this package doesn’t support references ($ref). However, the feature is on the roadmap. In the meantime, use json-ref-resolver or swagger-cli to resolve your references.

Table of Contents

• Install
• Get Started
• Uninstall
• Roadmap
• License

Install

If you’d like to try openapi-hook before it’s published, clone the repo:

gh repo clone christianareas/openapi-hook

Change to the openapi-hook directory, install, and build:

cd openapi-hook
npm i
npm run build

Link openapi-hook to your local system:

npm link

Change to your project’s directory and link it to openapi-hook:

cd path/to/your-project
npm link openapi-hook

Get Started

Set Up the OpenAPI Data Provider

The OpenAPI data provider gives the OpenAPI data hook access to the data from your OpenAPI specification. You must set this up before you can use the hook.

To set it up, import OpenApiDataProvider, use it to wrap your app or the API docs portion of your app, and pass it the URL to your OpenAPI specification:

import { OpenApiDataProvider } from "openapi-hook"
import OpenApiDoc from "./components/OpenApiDoc"

...

export default function DocsApiPage() {
	const urlToOpenApiFile = "https://raw.githubusercontent.com/christianareas/resume/main/docs/spec/_versions/resume-api-0.1.1.yaml"

	return (
		<OpenApiDataProvider
			urlToOpenApiFile={urlToOpenApiFile}
		>
			<OpenApiDoc />
		</OpenApiDataProvider>
	)
}

Use the OpenAPI Data Hook

The OpenAPI data hook gives you direct access to the data from your OpenAPI specification. The hook gives you full control of the elements of your OpenAPI specification.

To get started, import useOpenApiData, use it to save your OpenAPI data, and start building your API documentation. All the OpenAPI objects and fields you passed to OpenApiDataProvider are available through the hook. For example:

import { useOpenApiData } from "openapi-hook"

...

export default function OpenApiDoc() {
	const openApiData = useOpenApiData()

	return (
		<div>
			<h1>
				{openApiData.info.title} (<span>{openApiData.info.version}</span>)
			</h1>
			
			...
			
		</div>
	)
}

TypeScript

If you’d like to type your OpenAPI data, import Oas_3_1_0_Type and use it to type openApiData:

import { useOpenApiData, Oas_3_1_0_Type } from "openapi-hook"

...

export default function OpenApiDoc() {
	const openApiData: Oas_3_1_0_Type = useOpenApiData()

...

Uninstall

Change to your project’s directory and unlink it from openapi-hook:

cd path/to/your-project
npm unlink openapi-hook

Change to the openapi-hook directory and unlink openapi-hook from your local system:

cd path/to/openapi-hook
npm unlink -g

Roadmap

Beta

• Add OpenAPI type definition (based on OAS 3.1).
• Add basic error handling.
• Add OpenAPI hook.
• Add a docs site and publish it to GitHub Pages.
• Add reference ($ref) support.

Future

• Add basic caching.
• Add OAS 3.0 support.
• Add a component library (separate NPM module).

License

See LICENSE (GNU GPLv3).