OpenAPI Reference Plugin (Swagger/Scalar)

Serve interactive API reference documentation powered by Scalar or Swagger UI and expose your 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
      },
    }),
  ]
})

By default, the docs UI and OpenAPI specification are publicly accessible. Use allow to serve them conditionally. When it resolves to false, the request falls through as unmatched, as if the plugin were not installed.

const handler = new OpenAPIHandler(router, {
  plugins: [
    new OpenAPIReferenceHandlerPlugin({
      spec: () => generator.generate(router),
      allow: async ({ context }) => context.user !== undefined,
    }),
  ]
})

Learn More

For implementation details, see the source code.