OpenAPI Reference Plugin (Swagger/Scalar)

This plugin serves API reference documentation powered by Scalar or Swagger UI, and exposes the OpenAPI specification as JSON.

Setup

To use this plugin, first create an OpenAPI Generator. The plugin uses it to generate the OpenAPI specification.

import { OpenAPIGenerator } from '@orpc/openapi'
import { OpenAPIReferenceHandlerPlugin } from '@orpc/openapi/plugins'

const generator = new OpenAPIGenerator({
  converters: [
    new ZodToJsonSchemaConverter(),
  ],
})

const handler = new OpenAPIHandler(router, {
  plugins: [
    new OpenAPIReferenceHandlerPlugin({
      spec: () => generator.generate(router, {
        base: {
          info: {
            title: 'ORPC Playground',
            version: '1.0.0',
          },
          servers: [
            { url: 'https://api.example.com/v1', },
          ],
        },
      }),
    }),
  ]
})

Provider

Scalar is the default provider. To use Swagger UI instead, set provider to 'swagger'. Use providerConfig to pass provider-specific options.

const handler = new OpenAPIHandler(router, {
  plugins: [
    new OpenAPIReferenceHandlerPlugin({
      provider: 'swagger',
      providerConfig: {
        // Swagger UI specific configuration
      },
    }),
  ]
})

Learn More

For implementation details, see the source code.