Skip to main content

Get started

Speccy renders OpenAPI 3.x and Swagger 2 documents as searchable reference documentation. Use the React package inside an existing app, the Docusaurus plugin inside a documentation site, or the standalone starter when the API reference is the whole site.

Choose a package​

What you’re buildingStart with
A reference inside a React applicationspeccy-renderer
A reference alongside guides in Docusaurusdocusaurus-plugin-speccy
A dedicated public API referencecreate-speccy-reference
API linting and breaking-change checks in CIspeccy-cli

The Speccy Studio is for opening and reviewing specifications. It isn’t the production hosting shell.

React​

Install the renderer:

npm install speccy-renderer

Pass it a parsed OpenAPI object, a YAML string, or a JSON string:

import { Speccy } from 'speccy-renderer';
import 'speccy-renderer/styles.css';

export function ApiReference({ spec }) {
  return <Speccy spec={spec} basePath="/api" />;
}

basePath should match the route where the reference is mounted. Speccy uses it to create stable links for endpoints, tags, and reusable components.

Use the GitHub Action to review OpenAPI changes and enforce repository rules in pull requests.

Docusaurus​

Install the plugin:

npm install docusaurus-plugin-speccy

Add a generated reference route to docusaurus.config.ts:

export default {
  plugins: [
    [
      'docusaurus-plugin-speccy',
      {
        route: '/api',
        spec: './static/openapi.yaml',
      },
    ],
  ],
};

Run your normal Docusaurus development server. The reference will be available at /api.

Standalone​

Create a static reference site without adopting Docusaurus:

npm create speccy-reference my-api-reference
cd my-api-reference
npm install
npm run dev

Edit speccy.config.ts, then run npm run build. The generated app belongs to your project, so you can add analytics, authentication, custom headers, or other site-specific behavior without a Speccy plugin system.

What the spec needs​

At minimum, provide an OpenAPI version and a path:

openapi: 3.1.0
info:
  title: Library API
  version: 1.0.0
paths:
  /books:
    get:
      operationId: list-books
      summary: List books
      responses:
        '200':
          description: Books in the catalog

Add tags to group operations and give each operation an operationId. Speccy can create an ID from the method and path, but an explicit ID keeps URLs stable when paths change.

Next steps​