Scalar OpenAPI Types


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

Installation

``bash
npm add @scalar/openapi-types
`

Usage

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

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

$3

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

`ts
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:

`ts
// Import 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:

`ts
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:

`ts
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:

License

The source code in this repository is licensed under MIT.