scalarScalar 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.