OpenAPI Documentation

Igniter.js provides automatic OpenAPI spec generation and an optional interactive UI to explore your API. This page explains how to configure, generate, and serve documentation, and how to customize metadata and security.

Overview

  • Generate openapi.json via CLI: igniter generate docs.
  • Serve Igniter Studio (Scalar API Reference) in development with igniter dev --docs, or in production via the Core playground config.
  • Customize metadata via the .docs() method in your Igniter builder (info, servers, securitySchemes, and playground).

Generate the OpenAPI spec

You can generate the OpenAPI specification for your app using the CLI:

Code
npx @igniter-js/cli generate docs --output ./docs/openapi.json
  • Use the --ui flag to also generate an HTML page with Scalar API Reference UI:
Code
npx @igniter-js/cli generate docs --output ./docs --ui

This will create ./docs/openapi.json and ./docs/index.html.

Serve documentation with Igniter Studio

During development, you can enable Igniter Studio on your local server with:

Code
npx @igniter-js/cli dev --docs --docs-output ./docs
  • --docs enables OpenAPI generation and the interactive UI.
  • --docs-output controls where to save/serve files. By default, Studio is exposed at /docs.

In production, you can enable it via the Core configuration (see below) to serve openapi.json and Scalar UI directly from your app.

Configure via Igniter Builder

You can configure documentation metadata and security using the .docs() method in your Igniter builder:

Code
import { Igniter } from '@igniter-js/core'
import openapi from './docs/openapi.json'

export const igniter = Igniter
  .context(createIgniterAppContext())
  .store(store)
  .logger(logger)
  .config({
    baseURL: process.env.NEXT_PUBLIC_IGNITER_API_URL || 'http://localhost:3000',
    basePATH: process.env.NEXT_PUBLIC_IGNITER_API_BASE_PATH || '/api/v1',
  })
  .docs({
    openapi,
    info: {
      title: "My API",
      version: "1.0.0",
      description: "API description",
      contact: {
        name: 'Your Team',
        email: 'team@example.com',
        url: 'https://github.com/your-org/your-repo'
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT'
      }
    },
    servers: [{ url: "https://api.example.com", description: "Prod" }],
    securitySchemes: {
      bearerAuth: {
        type: "http",
        scheme: "bearer",
        bearerFormat: "JWT",
      },
    },
    playground: {
      enabled: true,
      route: "/docs",
      security: ({ request }) => {
        // Return false to block or an object with headers to allow
        return { headers: { Authorization: request.headers.get("authorization") ?? "" } }
      },
    },
  })
  .create()
  • The openapi field should reference your generated OpenAPI specification file.
  • info, servers, and securitySchemes feed into the OpenAPI document and override any existing metadata.
  • playground.enabled and playground.route control where the UI is served.
  • The playground.security function lets you block access or inject headers (such as a token) for calls made by the UI.

Production security

If no security function is provided, Igniter Studio is automatically disabled in production to avoid unintended exposure. To enable it safely, provide the security function and implement your authorization logic (e.g., validate session/cookies or headers). In development, the Studio remains accessible by default.

Best practices

  • Define servers to reflect your environments (dev/stage/prod).
  • Use securitySchemes to standardize authentication (Bearer, API Key, etc.).
  • In production, always implement playground.security and consider protecting the /docs route behind authentication.
  • Generate openapi.json in CI to keep documentation up-to-date.

Common Issues