Scalar OpenAPI Types

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

Installation

1npm add @scalar/openapi-types

Usage

1import type { OpenAPI } from '@scalar/openapi-types'
2
3const file: OpenAPI.Document = {
4  openapi: '3.1.0',
5  info: {
6    title: 'Hello World',
7    version: '1.0.0',
8  },
9  paths: {},
10}

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.

1import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/unprocessed'
2
3OpenApiObjectSchema.parse({
4  // This will be omitted:
5  invalidAttribute: 123,
6  // Those will pass:
7  openapi: '3.1.1',
8  info: {
9    title: 'Example API',
10    version: '1.0'
11  },
12  paths: {
13    '/example': {
14      get: {
15        description: 'My example operation',
16      }
17    }
18  },
19})

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:

1// Impport the Zod Schema without the $ref property:
2import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/processed'
3
4OpenApiObjectSchema.parse({
5  // …
6})

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:

1import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/unprocessed'
2import { XScalarIconSchema } from '@scalar/openapi-types/schemas/extensions'
3
4const MyCustomSchema = OpenApiObjectSchema
5  // Add the `x-scalar-icon` OpenAPI extension
6  .merge(
7    XScalarIconSchema
8  )
9  // Add a custom property
10  .extend({
11    'x-customProperty': z.boolean().optional(),
12  })

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

1import { OpenApiObjectSchema } from '@scalar/openapi-types/schemas/3.1/unprocessed'
2import { XScalarIconSchema } from '@scalar/openapi-types/schemas/extensions'
3
4const MyCustomSchema = OpenApiObjectSchema
5  .extend({
6    // Overwrite the Schema
7    'info': InfoObjectSchema.extend({
8      // Add a custom property
9      'x-customProperty': z.boolean().optional(),
10    }),
11  })

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.