OpenAPI Reference Plugin (Swagger/Scalar)

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

INFO

This plugin depends on the OpenAPI Generator. Review that guide before setting up the reference plugin.

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 { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'

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

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

INFO

By default, the API reference UI is served from /, and the OpenAPI specification is served from /spec.json. Use docsPath and specPath to change these routes.

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 OpenAPIReferencePlugin({
      provider: 'swagger',
      providerConfig: {
        // Swagger UI specific configuration
      },
    }),
  ]
})

INFO

You can also load custom assets for the docs UI by setting providerScriptUrl and providerCssUrl.

Learn More

For implementation details, see the source code.