@scalar/openapi-types 0.1.8 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @scalar/openapi-types
 
+## 0.2.0
+
+### Minor Changes
+
+- e62e677: feat: OpenAPI-compliant Zod Schemas
+
+### Patch Changes
+
+- 82f16a5: feat: add more Zod schemas for OpenAPI extensions
+
+## 0.1.9
+
+### Patch Changes
+
+- c10bbf5: chore: code style
+
 ## 0.1.8
 
 ### Patch Changes

package/README.md

@@ -28,6 +28,82 @@ const file: OpenAPI.Document = {
 }
 ```
 
+### 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.
+
+```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 `$ref`s (references).
+
+We also provide Zod schemas for processed OpenAPI documents, where the `$ref`s are resolved already:
+
+```ts
+// 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:
+
+```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: <https://discord.gg/scalar>