@scalar/openapi-types

Scalar OpenAPI Types

Modern OpenAPI parser written in TypeScript, with support for Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1

Installation

npm add @scalar/openapi-types

Usage

import type { OpenAPI } from '@scalar/openapi-types'

const file: OpenAPI.Document = {
  openapi: '3.1.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
}

Zod Schemas

Experimental: This package exposes OpenAPI-compliant Zod schemas for all OpenAPI object types. You can use them to parse user input safely with Zod.

import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/unprocessed'

OpenApiObjectSchema.parse({
  // This will be omitted:
  invalidAttribute: 123,
  // Those will pass:
  openapi: '3.1.1',
  info: {
    title: 'Example API',
    version: '1.0'
  },
  paths: {
    '/example': {
      get: {
        description: 'My example operation',
      }
    }
  },
})

What's “unprocessed”? It's for the content of a “raw” OpenAPI document, that might still contain $refs (references).

We also provide Zod schemas for processed OpenAPI documents, where the $refs are resolved already:

// Impport the Zod Schema without the $ref property:
import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/processed'

OpenApiObjectSchema.parse({
  // …
})

Extend the Zod schemas

While you can absolutely use the Zod schemas directly, you can also extend and compose them.

Here is a basic example to add an extension on the top level:

import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/unprocessed'
import { XScalarIconSchema } from '@scalar/openapi-types/schemas/extensions'

const MyCustomSchema = OpenApiObjectSchema
  // Add the `x-scalar-icon` OpenAPI extension
  .merge(
    XScalarIconSchema
  )
  // Add a custom property
  .extend({
    'x-customProperty': z.boolean().optional(),
  })

This will get a little bit more complex when you want to add a property to something that's deeply nested:

import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/unprocessed'
import { XScalarIconSchema } from '@scalar/openapi-types/schemas/extensions'

const MyCustomSchema = OpenApiObjectSchema
  .extend({
    // Overwrite the Schema
    'info': InfoObjectSchema.extend({
      // Add a custom property
      'x-customProperty': z.boolean().optional(),
    }),
  })

Community

We are API nerds. You too? Let's chat on Discord: https://discord.gg/scalar

License

The source code in this repository is licensed under MIT.