Get started

Speccy renders OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. 3.x and SwaggerSwaggerThe former name of the OpenAPI Specification. Swagger 2.0 documents are still common and are supported by Speccy. 2 documents as searchable reference documentation. OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. 3.0.3 and 3.1.1 are covered by compatibility fixtures in CI. See OpenAPI support for the tested objects and schema features.

Use the React package inside an existing app, the Docusaurus plugin inside a documentation site, or the standalone starter when the API referenceAPI referenceDocumentation organized around an API's operations, inputs, responses, schemas, and reusable components. is the whole site.

Choose a package

What you’re building	Start with
A reference inside a React application	speccy-renderer
A reference alongside guides in Docusaurus	docusaurus-plugin-speccy
A dedicated public API referenceAPI referenceDocumentation organized around an API's operations, inputs, responses, schemas, and reusable components.	create-speccy-reference
API linting and breaking-change checks in CI	speccy-cli

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

See Speccy Studio to open your own document or explore a catalog of public APIs.

React

Install the renderer:

npm install speccy-renderer

Pass it a parsed OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. 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 OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. 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 OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. 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

• Use Speccy Studio to explore a local, remote, or public OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. document.
• See Test API requests to configure servers, authorization, and browser requests.
• Read Review API health to use the same checks in the renderer, Studio, CLI, and GitHub Action.
• Use the React renderer for component options and routing behavior.
• Use the Docusaurus plugin for generated routes and MDX embeds.
• See OpenAPI extensions for tag groups, longer introductions, and icons.