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.
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
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>
)
}
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>
)
}
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()
...
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
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.
- Add basic caching.
- Add OAS 3.0 support.
- Add a component library (separate NPM module).
See LICENSE (GNU GPLv3).