From adc25abc0b48db9c54af62aaa0d086f85a5ff063 Mon Sep 17 00:00:00 2001 From: Luke Hagar Date: Thu, 25 Sep 2025 14:57:24 +0000 Subject: [PATCH] Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions. --- .cursor/rules/jsdoc-formatting.mdc | 10 +- .gitignore | 3 + 2.0.0/data-types/boolean.ts | 172 - 2.0.0/data-types/file.ts | 171 - 2.0.0/data-types/index.ts | 14 - 2.0.0/data-types/integer.ts | 234 -- 2.0.0/data-types/number.ts | 239 -- 2.0.0/data-types/object.ts | 205 - 2.0.0/data-types/schema.ts | 107 - 2.0.0/data-types/string.ts | 215 -- 2.0.0/index.ts | 107 - 2.0.0/info.ts | 205 - 2.0.0/paths.ts | 988 ----- 2.0.0/schema.ts | 378 -- 2.0.0/security.ts | 216 -- 2.0.0/spec.ts | 225 -- 2.0.0/xml.ts | 142 - {2.0.0 => 2.0}/2.0.md | 0 {2.0.0 => 2.0}/data-types/array.ts | 129 +- 2.0/data-types/boolean.ts | 172 + 2.0/data-types/file.ts | 171 + 2.0/data-types/index.ts | 10 + 2.0/data-types/integer.ts | 234 ++ 2.0/data-types/number.ts | 239 ++ 2.0/data-types/object.ts | 206 + 2.0/data-types/string.ts | 225 ++ {2.0.0 => 2.0}/example.ts | 30 +- {2.0.0 => 2.0}/extensions.ts | 36 +- {2.0.0 => 2.0}/externalDocs.ts | 66 +- 2.0/index.ts | 77 + 2.0/info.ts | 226 ++ 2.0/paths.ts | 1220 ++++++ {2.0.0 => 2.0}/references.ts | 46 +- 2.0/schema.ts | 316 ++ 2.0/security.ts | 236 ++ 2.0/spec.ts | 236 ++ 2.0/status.ts | 935 +++++ {2.0.0 => 2.0}/tags.ts | 96 +- 2.0/xml.ts | 142 + 3.0.x/components.ts | 123 - 3.0.x/data-types/array.ts | 206 - 3.0.x/data-types/boolean.ts | 165 - 3.0.x/data-types/composition.ts | 207 - 3.0.x/data-types/index.ts | 9 - 3.0.x/data-types/integer.ts | 223 -- 3.0.x/data-types/number.ts | 225 -- 3.0.x/data-types/object.ts | 256 -- 3.0.x/data-types/string.ts | 207 - 3.0.x/externalDocs.ts | 57 - 3.0.x/index.ts | 65 - 3.0.x/info.ts | 295 -- 3.0.x/paths.ts | 1206 ------ 3.0.x/references.ts | 49 - 3.0.x/security.ts | 225 -- 3.0.x/servers.ts | 197 - 3.0.x/spec.ts | 200 - 3.0.x/tags.ts | 84 - 3.0.x/xml.ts | 91 - {3.0.x => 3.0}/3.0.0.md | 0 {3.0.x => 3.0}/3.0.1.md | 0 {3.0.x => 3.0}/3.0.2.md | 0 {3.0.x => 3.0}/3.0.3.md | 0 {3.0.x => 3.0}/3.0.4.md | 0 3.0/components.ts | 214 ++ 3.0/data-types/array.ts | 209 + 3.0/data-types/boolean.ts | 167 + 3.0/data-types/composition.ts | 210 + 3.0/data-types/index.ts | 10 + 3.0/data-types/integer.ts | 225 ++ 3.0/data-types/number.ts | 227 ++ 3.0/data-types/object.ts | 259 ++ {3.0.x => 3.0}/data-types/reference.ts | 38 +- 3.0/data-types/string.ts | 344 ++ {3.0.x => 3.0}/extensions.ts | 6 +- 3.0/externalDocs.ts | 75 + 3.0/index.ts | 65 + 3.0/info.ts | 575 +++ 3.0/paths.ts | 2039 ++++++++++ 3.0/references.ts | 58 + {3.0.x => 3.0}/schema.ts | 124 +- 3.0/security.ts | 571 +++ 3.0/servers.ts | 251 ++ 3.0/spec.ts | 255 ++ 3.0/status.ts | 999 +++++ 3.0/tags.ts | 111 + 3.0/xml.ts | 136 + 3.1.x/components.ts | 134 - 3.1.x/data-types/array.ts | 202 - 3.1.x/data-types/boolean.ts | 121 - 3.1.x/data-types/composition.ts | 189 - 3.1.x/data-types/index.ts | 8 - 3.1.x/data-types/integer.ts | 178 - 3.1.x/data-types/number.ts | 178 - 3.1.x/data-types/object.ts | 217 -- 3.1.x/data-types/string.ts | 159 - 3.1.x/info.ts | 263 -- 3.1.x/paths.ts | 1446 ------- 3.1.x/schema.ts | 255 -- 3.1.x/security.ts | 358 -- 3.1.x/servers.ts | 164 - 3.1.x/spec.ts | 208 - 3.1.x/xml.ts | 117 - {3.1.x => 3.1}/3.1.0.md | 0 {3.1.x => 3.1}/3.1.1.md | 0 3.1/components.ts | 143 + 3.1/data-types/array.ts | 210 + 3.1/data-types/boolean.ts | 129 + 3.1/data-types/composition.ts | 197 + 3.1/data-types/index.ts | 9 + 3.1/data-types/integer.ts | 186 + 3.1/data-types/null.ts | 108 + 3.1/data-types/number.ts | 186 + 3.1/data-types/object.ts | 225 ++ {3.1.x => 3.1}/data-types/reference.ts | 36 +- 3.1/data-types/string.ts | 194 + {3.1.x => 3.1}/extensions.ts | 20 +- {3.1.x => 3.1}/externalDocs.ts | 40 +- {3.1.x => 3.1}/index.ts | 135 +- 3.1/info.ts | 263 ++ 3.1/paths.ts | 1377 +++++++ {3.1.x => 3.1}/references.ts | 58 +- 3.1/schema.ts | 254 ++ 3.1/security.ts | 366 ++ 3.1/servers.ts | 164 + 3.1/spec.ts | 209 + 3.1/status.ts | 999 +++++ {3.1.x => 3.1}/tags.ts | 90 +- 3.1/webhooks.ts | 131 + 3.1/xml.ts | 117 + {3.2.0 => 3.2}/3.2.0.md | 0 3.2/components.ts | 1223 ++++++ 3.2/data-types/array.ts | 202 + 3.2/data-types/boolean.ts | 120 + 3.2/data-types/composition.ts | 189 + 3.2/data-types/index.ts | 8 + 3.2/data-types/integer.ts | 177 + 3.2/data-types/number.ts | 177 + 3.2/data-types/object.ts | 217 ++ 3.2/data-types/reference.ts | 70 + 3.2/data-types/string.ts | 158 + 3.2/extensions.ts | 62 + 3.2/externalDocs.ts | 62 + 3.2/index.ts | 60 + 3.2/info.ts | 350 ++ 3.2/oauth.ts | 223 ++ 3.2/paths.ts | 716 ++++ 3.2/references.ts | 84 + 3.2/schema.ts | 238 ++ 3.2/security.ts | 32 + 3.2/servers.ts | 191 + 3.2/spec.ts | 281 ++ 3.2/status.ts | 999 +++++ 3.2/tags.ts | 80 + 3.2/webhooks.ts | 130 + 3.2/xml.ts | 116 + License.ts | 87 +- MIGRATION.md | 102 - README.md | 150 +- SPDXLicenseList.ts | 4446 +++++++++++----------- biome.json | 22 + bunfig.toml | 4 - index.ts | 31 +- package.json | 212 +- pnpm-lock.yaml | 1033 +++++ tests/2.0/api-with-examples.ts | 147 + tests/2.0/petstore-expanded.ts | 202 + tests/2.0/petstore-minimal.ts | 61 + tests/2.0/petstore-simple.ts | 212 ++ tests/2.0/petstore-with-external-docs.ts | 223 ++ tests/2.0/petstore.ts | 137 + tests/2.0/uber.ts | 372 ++ tests/3.0/api-with-examples.ts | 194 + tests/3.0/callback-example.ts | 88 + tests/3.0/link-example.ts | 321 ++ tests/3.0/petstore-expanded.ts | 240 ++ tests/3.0/petstore.ts | 179 + tests/3.0/uspto.ts | 257 ++ tests/3.1/non-oauth-scopes.ts | 34 + tests/3.1/tictactoe.ts | 266 ++ tests/3.1/webhook-example.ts | 50 + tsconfig.json | 51 +- 181 files changed, 30313 insertions(+), 14953 deletions(-) delete mode 100644 2.0.0/data-types/boolean.ts delete mode 100644 2.0.0/data-types/file.ts delete mode 100644 2.0.0/data-types/index.ts delete mode 100644 2.0.0/data-types/integer.ts delete mode 100644 2.0.0/data-types/number.ts delete mode 100644 2.0.0/data-types/object.ts delete mode 100644 2.0.0/data-types/schema.ts delete mode 100644 2.0.0/data-types/string.ts delete mode 100644 2.0.0/index.ts delete mode 100644 2.0.0/info.ts delete mode 100644 2.0.0/paths.ts delete mode 100644 2.0.0/schema.ts delete mode 100644 2.0.0/security.ts delete mode 100644 2.0.0/spec.ts delete mode 100644 2.0.0/xml.ts rename {2.0.0 => 2.0}/2.0.md (100%) rename {2.0.0 => 2.0}/data-types/array.ts (50%) create mode 100644 2.0/data-types/boolean.ts create mode 100644 2.0/data-types/file.ts create mode 100644 2.0/data-types/index.ts create mode 100644 2.0/data-types/integer.ts create mode 100644 2.0/data-types/number.ts create mode 100644 2.0/data-types/object.ts create mode 100644 2.0/data-types/string.ts rename {2.0.0 => 2.0}/example.ts (63%) rename {2.0.0 => 2.0}/extensions.ts (73%) rename {2.0.0 => 2.0}/externalDocs.ts (59%) create mode 100644 2.0/index.ts create mode 100644 2.0/info.ts create mode 100644 2.0/paths.ts rename {2.0.0 => 2.0}/references.ts (77%) create mode 100644 2.0/schema.ts create mode 100644 2.0/security.ts create mode 100644 2.0/spec.ts create mode 100644 2.0/status.ts rename {2.0.0 => 2.0}/tags.ts (51%) create mode 100644 2.0/xml.ts delete mode 100644 3.0.x/components.ts delete mode 100644 3.0.x/data-types/array.ts delete mode 100644 3.0.x/data-types/boolean.ts delete mode 100644 3.0.x/data-types/composition.ts delete mode 100644 3.0.x/data-types/index.ts delete mode 100644 3.0.x/data-types/integer.ts delete mode 100644 3.0.x/data-types/number.ts delete mode 100644 3.0.x/data-types/object.ts delete mode 100644 3.0.x/data-types/string.ts delete mode 100644 3.0.x/externalDocs.ts delete mode 100644 3.0.x/index.ts delete mode 100644 3.0.x/info.ts delete mode 100644 3.0.x/paths.ts delete mode 100644 3.0.x/references.ts delete mode 100644 3.0.x/security.ts delete mode 100644 3.0.x/servers.ts delete mode 100644 3.0.x/spec.ts delete mode 100644 3.0.x/tags.ts delete mode 100644 3.0.x/xml.ts rename {3.0.x => 3.0}/3.0.0.md (100%) rename {3.0.x => 3.0}/3.0.1.md (100%) rename {3.0.x => 3.0}/3.0.2.md (100%) rename {3.0.x => 3.0}/3.0.3.md (100%) rename {3.0.x => 3.0}/3.0.4.md (100%) create mode 100644 3.0/components.ts create mode 100644 3.0/data-types/array.ts create mode 100644 3.0/data-types/boolean.ts create mode 100644 3.0/data-types/composition.ts create mode 100644 3.0/data-types/index.ts create mode 100644 3.0/data-types/integer.ts create mode 100644 3.0/data-types/number.ts create mode 100644 3.0/data-types/object.ts rename {3.0.x => 3.0}/data-types/reference.ts (71%) create mode 100644 3.0/data-types/string.ts rename {3.0.x => 3.0}/extensions.ts (93%) create mode 100644 3.0/externalDocs.ts create mode 100644 3.0/index.ts create mode 100644 3.0/info.ts create mode 100644 3.0/paths.ts create mode 100644 3.0/references.ts rename {3.0.x => 3.0}/schema.ts (60%) create mode 100644 3.0/security.ts create mode 100644 3.0/servers.ts create mode 100644 3.0/spec.ts create mode 100644 3.0/status.ts create mode 100644 3.0/tags.ts create mode 100644 3.0/xml.ts delete mode 100644 3.1.x/components.ts delete mode 100644 3.1.x/data-types/array.ts delete mode 100644 3.1.x/data-types/boolean.ts delete mode 100644 3.1.x/data-types/composition.ts delete mode 100644 3.1.x/data-types/index.ts delete mode 100644 3.1.x/data-types/integer.ts delete mode 100644 3.1.x/data-types/number.ts delete mode 100644 3.1.x/data-types/object.ts delete mode 100644 3.1.x/data-types/string.ts delete mode 100644 3.1.x/info.ts delete mode 100644 3.1.x/paths.ts delete mode 100644 3.1.x/schema.ts delete mode 100644 3.1.x/security.ts delete mode 100644 3.1.x/servers.ts delete mode 100644 3.1.x/spec.ts delete mode 100644 3.1.x/xml.ts rename {3.1.x => 3.1}/3.1.0.md (100%) rename {3.1.x => 3.1}/3.1.1.md (100%) create mode 100644 3.1/components.ts create mode 100644 3.1/data-types/array.ts create mode 100644 3.1/data-types/boolean.ts create mode 100644 3.1/data-types/composition.ts create mode 100644 3.1/data-types/index.ts create mode 100644 3.1/data-types/integer.ts create mode 100644 3.1/data-types/null.ts create mode 100644 3.1/data-types/number.ts create mode 100644 3.1/data-types/object.ts rename {3.1.x => 3.1}/data-types/reference.ts (66%) create mode 100644 3.1/data-types/string.ts rename {3.1.x => 3.1}/extensions.ts (78%) rename {3.1.x => 3.1}/externalDocs.ts (57%) rename {3.1.x => 3.1}/index.ts (79%) create mode 100644 3.1/info.ts create mode 100644 3.1/paths.ts rename {3.1.x => 3.1}/references.ts (55%) create mode 100644 3.1/schema.ts create mode 100644 3.1/security.ts create mode 100644 3.1/servers.ts create mode 100644 3.1/spec.ts create mode 100644 3.1/status.ts rename {3.1.x => 3.1}/tags.ts (58%) create mode 100644 3.1/webhooks.ts create mode 100644 3.1/xml.ts rename {3.2.0 => 3.2}/3.2.0.md (100%) create mode 100644 3.2/components.ts create mode 100644 3.2/data-types/array.ts create mode 100644 3.2/data-types/boolean.ts create mode 100644 3.2/data-types/composition.ts create mode 100644 3.2/data-types/index.ts create mode 100644 3.2/data-types/integer.ts create mode 100644 3.2/data-types/number.ts create mode 100644 3.2/data-types/object.ts create mode 100644 3.2/data-types/reference.ts create mode 100644 3.2/data-types/string.ts create mode 100644 3.2/extensions.ts create mode 100644 3.2/externalDocs.ts create mode 100644 3.2/index.ts create mode 100644 3.2/info.ts create mode 100644 3.2/oauth.ts create mode 100644 3.2/paths.ts create mode 100644 3.2/references.ts create mode 100644 3.2/schema.ts create mode 100644 3.2/security.ts create mode 100644 3.2/servers.ts create mode 100644 3.2/spec.ts create mode 100644 3.2/status.ts create mode 100644 3.2/tags.ts create mode 100644 3.2/webhooks.ts create mode 100644 3.2/xml.ts delete mode 100644 MIGRATION.md create mode 100644 biome.json create mode 100644 pnpm-lock.yaml create mode 100644 tests/2.0/api-with-examples.ts create mode 100644 tests/2.0/petstore-expanded.ts create mode 100644 tests/2.0/petstore-minimal.ts create mode 100644 tests/2.0/petstore-simple.ts create mode 100644 tests/2.0/petstore-with-external-docs.ts create mode 100644 tests/2.0/petstore.ts create mode 100644 tests/2.0/uber.ts create mode 100644 tests/3.0/api-with-examples.ts create mode 100644 tests/3.0/callback-example.ts create mode 100644 tests/3.0/link-example.ts create mode 100644 tests/3.0/petstore-expanded.ts create mode 100644 tests/3.0/petstore.ts create mode 100644 tests/3.0/uspto.ts create mode 100644 tests/3.1/non-oauth-scopes.ts create mode 100644 tests/3.1/tictactoe.ts create mode 100644 tests/3.1/webhook-example.ts diff --git a/.cursor/rules/jsdoc-formatting.mdc b/.cursor/rules/jsdoc-formatting.mdc index ccc4833..e18c44b 100644 --- a/.cursor/rules/jsdoc-formatting.mdc +++ b/.cursor/rules/jsdoc-formatting.mdc @@ -17,7 +17,7 @@ The JSDoc comments should be formatted as follows: - property level comments for each field of the type that inlcude example values, with more detailed comments for the properties that are more complex. Ensure you Always: -- use the `@key` tag to document the fields of the type. +- use the `@property` tag to document the fields of the type. - use the `@see` tag to link to the official OpenAPI specification version they represent, and to the correct section. - use the `@example` tag to provide an example of the type. - use the `@note` tag to provide a note about the type. @@ -52,10 +52,10 @@ The example below is for the Contact Object: * ----------------------------------------------------------------------------- * * - * @key `name` - Optional The identifying name of the contact person/organization. - * @key `url` - Optional A URL pointing to the contact information. - * @key `email` - Optional The email address of the contact person/organization. - * @key `x-${string}` - Specification Extensions + * @property `name` - Optional The identifying name of the contact person/organization. + * @property `url` - Optional A URL pointing to the contact information. + * @property `email` - Optional The email address of the contact person/organization. + * @property `x-${string}` - Specification Extensions * * @note * All fields are optional. diff --git a/.gitignore b/.gitignore index a14702c..5f5dbd9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,9 @@ # dependencies (bun install) node_modules +reports/ + + # output out dist diff --git a/2.0.0/data-types/boolean.ts b/2.0.0/data-types/boolean.ts deleted file mode 100644 index ba3509d..0000000 --- a/2.0.0/data-types/boolean.ts +++ /dev/null @@ -1,172 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Boolean Schema - * ----- - * - * Schema for boolean data types in Swagger 2.0. - * - * Boolean schemas represent true/false values and are used for flags, switches, - * and other binary state indicators in APIs. They are simple but essential - * data types that provide clear semantic meaning for binary choices. - * - * Boolean schemas are commonly used for feature flags, status indicators, - * configuration options, and other binary state representations. They support - * default values and examples to help API consumers understand the expected - * behavior. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "boolean" for boolean schemas. - * @key `description` - A short description of the boolean schema. - * @key `title` - A short title for the boolean schema. - * @key `default` - Declares the default value for the boolean. - * @key `example` - Example boolean value. - * - * @note - * Boolean schemas inherit common properties from BaseSchemaProperties. - * No additional validation properties are needed for boolean values as they - * are inherently simple (true/false only). - * - * ----- - * Examples - * ----- - * - * @example (feature flag boolean): - * ```ts - * const featureFlagSchema: BooleanSchema = { - * type: "boolean", - * description: "Whether the new feature is enabled", - * default: false, - * example: true - * }; - * ``` - * - * @example (status boolean): - * ```ts - * const isActiveSchema: BooleanSchema = { - * type: "boolean", - * description: "Whether the user account is active", - * default: true, - * example: true - * }; - * ``` - * - * @example (configuration boolean): - * ```ts - * const notificationsEnabledSchema: BooleanSchema = { - * type: "boolean", - * description: "Whether email notifications are enabled", - * default: true, - * example: false - * }; - * ``` - * - * @example (permission boolean): - * ```ts - * const canEditSchema: BooleanSchema = { - * type: "boolean", - * description: "Whether the user can edit this resource", - * example: true - * }; - * ``` - */ -export interface BooleanSchema extends Extension { - /** - * The type of the schema. Must be "boolean" for boolean schemas. - * - * This property is required and must be set to "boolean" to indicate - * that this schema represents true/false values. - * - * @example "boolean" - */ - type: "boolean" - - /** - * The extending format for the previously mentioned type. - * See Swagger 2.0 Data Type Formats for further details. - * - * Formats provide additional semantic information about the data type, - * enabling more precise validation and better tooling support. Swagger 2.0 - * defines several standard formats, but custom formats are also allowed. - * - * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} - * - * @example "int32" - * @example "date" - * @example "email" - * @example "uuid" - */ - format?: string - - /** - * A short description of the schema. GFM syntax can be used for rich text representation. - * - * This description should provide clear information about what the schema - * represents and how it should be used. It's commonly displayed in API - * documentation and code generation tools. - * - * @example "A user object containing basic information" - * @example "Email address in RFC 5322 format" - */ - description?: string - - /** - * A short title for the schema. - * - * The title provides a human-readable name for the schema, often used - * in documentation and UI displays. It should be concise but descriptive. - * - * @example "User" - * @example "Pet" - * @example "Order" - */ - title?: string - - /** - * Declares the value of the schema that the server will use if none is provided. - * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. - * - * This is a Swagger 2.0 specific requirement that differs from JSON Schema. - * The default value must be valid according to the schema's type and constraints. - * - * @example "defaultValue" - * @example 10 - * @example { name: "John", age: 30 } - * @example ["item1", "item2"] - */ - default?: unknown - - /** - * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} - * - * @example ["option1", "option2", "option3"] - * @example ["red", "green", "blue"] - * @example [1, 2, 3, 4, 5] - */ - enum?: unknown[] - - /** - * A free-form property to include an example of an instance for this schema. - * - * Examples help developers understand how to use the schema and what kind - * of data is expected. They are commonly used by documentation generators - * and API testing tools. - * - * @example { name: "Puma", id: 1 } - * @example "example string value" - * @example 42 - * @example ["item1", "item2"] - */ - example?: unknown -} diff --git a/2.0.0/data-types/file.ts b/2.0.0/data-types/file.ts deleted file mode 100644 index 8f1357a..0000000 --- a/2.0.0/data-types/file.ts +++ /dev/null @@ -1,171 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * File Schema - * ----- - * - * Schema for file data types in Swagger 2.0. - * - * File schemas represent file uploads and downloads in APIs. This is a Swagger 2.0 - * specific data type that extends the JSON Schema specification to support file - * operations. File schemas are used by Parameter and Response objects to indicate - * that the data represents a file rather than a structured data type. - * - * File schemas are commonly used for file upload endpoints, document processing, - * image handling, and other file-based operations. They provide clear indication - * to API consumers that file data is expected or returned. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * | 2.0 | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} | - * | 2.0 | {@link https://swagger.io/specification/v2/#response-object | Swagger 2.0 Response Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "file" for file schemas. - * @key `description` - A short description of the file schema. - * @key `title` - A short title for the file schema. - * @key `example` - Example file information or description. - * - * @note - * File schemas are specific to Swagger 2.0 and are not part of the JSON Schema - * specification. They inherit common properties from BaseSchemaProperties. - * When used in parameters, the consumes property should specify appropriate - * MIME types like "multipart/form-data" or "application/x-www-form-urlencoded". - * - * ----- - * Examples - * ----- - * - * @example (file upload parameter): - * ```ts - * const fileUploadSchema: FileSchema = { - * type: "file", - * description: "Image file to upload", - * example: "user-avatar.jpg" - * }; - * ``` - * - * @example (document upload parameter): - * ```ts - * const documentSchema: FileSchema = { - * type: "file", - * description: "PDF document to process", - * example: "contract.pdf" - * }; - * ``` - * - * @example (file download response): - * ```ts - * const fileDownloadSchema: FileSchema = { - * type: "file", - * description: "Generated report file", - * example: "monthly-report.xlsx" - * }; - * ``` - * - * @example (image file parameter): - * ```ts - * const imageSchema: FileSchema = { - * type: "file", - * description: "Profile picture image", - * example: "profile-photo.png" - * }; - * ``` - */ -export interface FileSchema extends Extension { - /** - * The type of the schema. Must be "file" for file schemas. - * - * This property is required and must be set to "file" to indicate - * that this schema represents file data. This is a Swagger 2.0 specific - * type that extends JSON Schema. - * - * @example "file" - */ - type: "file" - - /** - * The extending format for the previously mentioned type. - * See Swagger 2.0 Data Type Formats for further details. - * - * Formats provide additional semantic information about the data type, - * enabling more precise validation and better tooling support. Swagger 2.0 - * defines several standard formats, but custom formats are also allowed. - * - * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} - * - * @example "int32" - * @example "date" - * @example "email" - * @example "uuid" - */ - format?: string - - /** - * A short description of the schema. GFM syntax can be used for rich text representation. - * - * This description should provide clear information about what the schema - * represents and how it should be used. It's commonly displayed in API - * documentation and code generation tools. - * - * @example "A user object containing basic information" - * @example "Email address in RFC 5322 format" - */ - description?: string - - /** - * A short title for the schema. - * - * The title provides a human-readable name for the schema, often used - * in documentation and UI displays. It should be concise but descriptive. - * - * @example "User" - * @example "Pet" - * @example "Order" - */ - title?: string - - /** - * Declares the value of the schema that the server will use if none is provided. - * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. - * - * This is a Swagger 2.0 specific requirement that differs from JSON Schema. - * The default value must be valid according to the schema's type and constraints. - * - * @example "defaultValue" - * @example 10 - * @example { name: "John", age: 30 } - * @example ["item1", "item2"] - */ - default?: unknown - - /** - * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} - * - * @example ["option1", "option2", "option3"] - * @example ["red", "green", "blue"] - * @example [1, 2, 3, 4, 5] - */ - enum?: unknown[] - - /** - * A free-form property to include an example of an instance for this schema. - * - * Examples help developers understand how to use the schema and what kind - * of data is expected. They are commonly used by documentation generators - * and API testing tools. - * - * @example { name: "Puma", id: 1 } - * @example "example string value" - * @example 42 - * @example ["item1", "item2"] - */ - example?: unknown -} diff --git a/2.0.0/data-types/index.ts b/2.0.0/data-types/index.ts deleted file mode 100644 index 263c987..0000000 --- a/2.0.0/data-types/index.ts +++ /dev/null @@ -1,14 +0,0 @@ -// Base schema properties -export type { BaseSchemaProperties } from "./base-schema" - -// Individual schema types -export type { StringSchema } from "./string" -export type { NumberSchema } from "./number" -export type { IntegerSchema } from "./integer" -export type { BooleanSchema } from "./boolean" -export type { FileSchema } from "./file" -export type { ArraySchema } from "./array" -export type { ObjectSchema } from "./object" - -// Main schema union type -export type { SwaggerSchema } from "./swagger-schema" diff --git a/2.0.0/data-types/integer.ts b/2.0.0/data-types/integer.ts deleted file mode 100644 index b02428f..0000000 --- a/2.0.0/data-types/integer.ts +++ /dev/null @@ -1,234 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Integer Schema - * ----- - * - * Schema for integer data types in Swagger 2.0. - * - * Integer schemas represent whole numbers without fractional components. - * They support various formats and validation rules to ensure data integrity - * and provide meaningful constraints for integer values. - * - * Integer schemas are commonly used for counts, IDs, timestamps, and other - * discrete numeric values in APIs. They support range validation and multiple - * format specifications including int32 and int64. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "integer" for integer schemas. - * @key `format` - The extending format for the integer type (e.g., "int32", "int64"). - * @key `description` - A short description of the integer schema. - * @key `title` - A short title for the integer schema. - * @key `default` - Declares the default value for the integer. - * @key `multipleOf` - The integer must be a multiple of this value. - * @key `maximum` - Maximum value for the integer. - * @key `exclusiveMaximum` - Whether the maximum value is exclusive. - * @key `minimum` - Minimum value for the integer. - * @key `exclusiveMinimum` - Whether the minimum value is exclusive. - * @key `example` - Example integer value. - * - * @note - * Integer schemas inherit common properties from BaseSchemaProperties and add - * numeric-specific validation properties. The `format` property is important - * for distinguishing between different integer representations (int32 vs int64). - * - * ----- - * Examples - * ----- - * - * @example (user ID integer): - * ```ts - * const userIdSchema: IntegerSchema = { - * type: "integer", - * format: "int64", - * description: "Unique user identifier", - * minimum: 1, - * example: 12345 - * }; - * ``` - * - * @example (age integer): - * ```ts - * const ageSchema: IntegerSchema = { - * type: "integer", - * format: "int32", - * description: "Person's age in years", - * minimum: 0, - * maximum: 150, - * example: 25 - * }; - * ``` - * - * @example (quantity integer): - * ```ts - * const quantitySchema: IntegerSchema = { - * type: "integer", - * format: "int32", - * description: "Item quantity", - * minimum: 0, - * maximum: 1000, - * multipleOf: 1, - * example: 5 - * }; - * ``` - * - * @example (timestamp integer): - * ```ts - * const timestampSchema: IntegerSchema = { - * type: "integer", - * format: "int64", - * description: "Unix timestamp in seconds", - * minimum: 0, - * example: 1640995200 - * }; - * ``` - */ -export interface IntegerSchema extends Extension { - /** - * The type of the schema. Must be "integer" for integer schemas. - * - * This property is required and must be set to "integer" to indicate - * that this schema represents whole number data without fractional components. - * - * @example "integer" - */ - type: "integer" - - /** - * The extending format for the previously mentioned type. - * See Swagger 2.0 Data Type Formats for further details. - * - * Formats provide additional semantic information about the data type, - * enabling more precise validation and better tooling support. Swagger 2.0 - * defines several standard formats, but custom formats are also allowed. - * - * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} - * - * @example "int32" - * @example "int64" - */ - format?: string - - /** - * A short description of the schema. GFM syntax can be used for rich text representation. - * - * This description should provide clear information about what the schema - * represents and how it should be used. It's commonly displayed in API - * documentation and code generation tools. - * - * @example "A user object containing basic information" - * @example "Email address in RFC 5322 format" - */ - description?: string - - /** - * A short title for the schema. - * - * The title provides a human-readable name for the schema, often used - * in documentation and UI displays. It should be concise but descriptive. - * - * @example "User" - * @example "Pet" - * @example "Order" - */ - title?: string - - /** - * Declares the value of the schema that the server will use if none is provided. - * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. - * - * This is a Swagger 2.0 specific requirement that differs from JSON Schema. - * The default value must be valid according to the schema's type and constraints. - * - * @example "defaultValue" - * @example 10 - * @example { name: "John", age: 30 } - * @example ["item1", "item2"] - */ - default?: unknown - - /** - * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} - * - * @example ["option1", "option2", "option3"] - * @example ["red", "green", "blue"] - * @example [1, 2, 3, 4, 5] - */ - enum?: unknown[] - - /** - * A free-form property to include an example of an instance for this schema. - * - * Examples help developers understand how to use the schema and what kind - * of data is expected. They are commonly used by documentation generators - * and API testing tools. - * - * @example { name: "Puma", id: 1 } - * @example "example string value" - * @example 42 - * @example ["item1", "item2"] - */ - example?: unknown - - /** - * A number is valid against "multipleOf" if the result of the division - * of the instance by this keyword's value is an integer. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 | JSON Schema Validation - multipleOf} - * - * @example 2 - * @example 1 - */ - multipleOf?: number - - /** - * A number is valid against "maximum" if it is less than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - maximum} - * - * @example 100 - * @example 2147483647 - */ - maximum?: number - - /** - * A number is valid against "exclusiveMaximum" if it is strictly less than this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - exclusiveMaximum} - * - * @example false - * @example true - */ - exclusiveMaximum?: boolean - - /** - * A number is valid against "minimum" if it is greater than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - minimum} - * - * @example 0 - * @example 1 - */ - minimum?: number - - /** - * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - exclusiveMinimum} - * - * @example false - * @example true - */ - exclusiveMinimum?: boolean -} diff --git a/2.0.0/data-types/number.ts b/2.0.0/data-types/number.ts deleted file mode 100644 index 6e71d1b..0000000 --- a/2.0.0/data-types/number.ts +++ /dev/null @@ -1,239 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Number Schema - * ----- - * - * Schema for number data types in Swagger 2.0. - * - * Number schemas represent numeric data including both integers and floating-point - * numbers. They support various formats and validation rules to ensure data - * integrity and provide meaningful constraints for numeric values. - * - * Number schemas are commonly used for quantities, prices, measurements, and - * other numeric data in APIs. They support range validation, precision control, - * and multiple format specifications. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "number" for number schemas. - * @key `format` - The extending format for the number type (e.g., "float", "double"). - * @key `description` - A short description of the number schema. - * @key `title` - A short title for the number schema. - * @key `default` - Declares the default value for the number. - * @key `multipleOf` - The number must be a multiple of this value. - * @key `maximum` - Maximum value for the number. - * @key `exclusiveMaximum` - Whether the maximum value is exclusive. - * @key `minimum` - Minimum value for the number. - * @key `exclusiveMinimum` - Whether the minimum value is exclusive. - * @key `example` - Example number value. - * - * @note - * Number schemas inherit common properties from BaseSchemaProperties and add - * numeric-specific validation properties. The `format` property is important - * for distinguishing between different numeric representations (float vs double). - * - * ----- - * Examples - * ----- - * - * @example (price number): - * ```ts - * const priceSchema: NumberSchema = { - * type: "number", - * format: "double", - * description: "Price in USD", - * minimum: 0, - * maximum: 999999.99, - * multipleOf: 0.01, - * example: 29.99 - * }; - * ``` - * - * @example (percentage number): - * ```ts - * const percentageSchema: NumberSchema = { - * type: "number", - * format: "float", - * description: "Percentage value", - * minimum: 0, - * maximum: 100, - * example: 85.5 - * }; - * ``` - * - * @example (coordinate number): - * ```ts - * const coordinateSchema: NumberSchema = { - * type: "number", - * format: "double", - * description: "Geographic coordinate", - * minimum: -180, - * maximum: 180, - * example: -122.4194 - * }; - * ``` - * - * @example (rating number): - * ```ts - * const ratingSchema: NumberSchema = { - * type: "number", - * format: "float", - * description: "User rating", - * minimum: 1, - * maximum: 5, - * multipleOf: 0.1, - * example: 4.5 - * }; - * ``` - */ -export interface NumberSchema extends Extension { - /** - * The type of the schema. Must be "number" for number schemas. - * - * This property is required and must be set to "number" to indicate - * that this schema represents numeric data (both integers and floating-point). - * - * @example "number" - */ - type: "number" - - /** - * The extending format for the previously mentioned type. - * See Swagger 2.0 Data Type Formats for further details. - * - * Formats provide additional semantic information about the data type, - * enabling more precise validation and better tooling support. Swagger 2.0 - * defines several standard formats, but custom formats are also allowed. - * - * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} - * - * @example "int32" - * @example "date" - * @example "email" - * @example "uuid" - */ - format?: string - - /** - * A short description of the schema. GFM syntax can be used for rich text representation. - * - * This description should provide clear information about what the schema - * represents and how it should be used. It's commonly displayed in API - * documentation and code generation tools. - * - * @example "A user object containing basic information" - * @example "Email address in RFC 5322 format" - */ - description?: string - - /** - * A short title for the schema. - * - * The title provides a human-readable name for the schema, often used - * in documentation and UI displays. It should be concise but descriptive. - * - * @example "User" - * @example "Pet" - * @example "Order" - */ - title?: string - - /** - * Declares the value of the schema that the server will use if none is provided. - * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. - * - * This is a Swagger 2.0 specific requirement that differs from JSON Schema. - * The default value must be valid according to the schema's type and constraints. - * - * @example "defaultValue" - * @example 10 - * @example { name: "John", age: 30 } - * @example ["item1", "item2"] - */ - default?: unknown - - /** - * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} - * - * @example ["option1", "option2", "option3"] - * @example ["red", "green", "blue"] - * @example [1, 2, 3, 4, 5] - */ - enum?: unknown[] - - /** - * A free-form property to include an example of an instance for this schema. - * - * Examples help developers understand how to use the schema and what kind - * of data is expected. They are commonly used by documentation generators - * and API testing tools. - * - * @example { name: "Puma", id: 1 } - * @example "example string value" - * @example 42 - * @example ["item1", "item2"] - */ - example?: unknown - - /** - * A number is valid against "multipleOf" if the result of the division - * of the instance by this keyword's value is an integer. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 | JSON Schema Validation - multipleOf} - * - * @example 2 - * @example 0.01 - */ - multipleOf?: number - - /** - * A number is valid against "maximum" if it is less than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - maximum} - * - * @example 100 - * @example 999.99 - */ - maximum?: number - - /** - * A number is valid against "exclusiveMaximum" if it is strictly less than this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - exclusiveMaximum} - * - * @example false - * @example true - */ - exclusiveMaximum?: boolean - - /** - * A number is valid against "minimum" if it is greater than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - minimum} - * - * @example 0 - * @example 1 - */ - minimum?: number - - /** - * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - exclusiveMinimum} - * - * @example false - * @example true - */ - exclusiveMinimum?: boolean -} diff --git a/2.0.0/data-types/object.ts b/2.0.0/data-types/object.ts deleted file mode 100644 index 917f12b..0000000 --- a/2.0.0/data-types/object.ts +++ /dev/null @@ -1,205 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Object Schema - * ----- - * - * Schema for object data types in Swagger 2.0. - * - * Object schemas represent structured data with named properties, where each - * property has its own schema definition. They are based on JSON Schema Draft 4 - * with Swagger-specific adjustments, providing comprehensive validation for - * complex data structures. - * - * Object schemas are commonly used for models, entities, and complex data - * structures in APIs. They support property definitions, required fields, - * additional properties, and composition through allOf. The properties - * reference Swagger Schema Objects instead of JSON Schema definitions. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "object" for object schemas. - * @key `properties` - The properties of the object. - * @key `required` - A list of required properties. - * @key `additionalProperties` - Additional properties for the object. - * @key `allOf` - An array of schemas that this schema must validate against. - * @key `description` - A short description of the object schema. - * @key `title` - A short title for the object schema. - * @key `default` - Declares the default value for the object. - * @key `maxProperties` - Maximum number of properties in the object. - * @key `minProperties` - Minimum number of properties in the object. - * @key `example` - Example object value. - * - * @note - * Object schemas inherit common properties from BaseSchemaProperties and add - * object-specific validation properties. The properties, additionalProperties, - * and allOf definitions reference the Swagger Schema Object instead of JSON Schema. - * - * ----- - * Examples - * ----- - * - * @example (simple object): - * ```ts - * const userSchema: ObjectSchema = { - * type: "object", - * properties: { - * id: { type: "integer", format: "int64" }, - * name: { type: "string" }, - * email: { type: "string", format: "email" } - * }, - * required: ["id", "name", "email"], - * example: { id: 1, name: "John Doe", email: "john@example.com" } - * }; - * ``` - * - * @example (object with additional properties): - * ```ts - * const configSchema: ObjectSchema = { - * type: "object", - * properties: { - * theme: { type: "string", enum: ["light", "dark"] }, - * language: { type: "string", default: "en" } - * }, - * additionalProperties: { type: "string" }, - * description: "User configuration with custom properties" - * }; - * ``` - * - * @example (object with composition): - * ```ts - * const extendedUserSchema: ObjectSchema = { - * type: "object", - * allOf: [ - * { $ref: "#/definitions/BaseUser" }, - * { - * type: "object", - * properties: { - * role: { type: "string", enum: ["admin", "user", "guest"] }, - * permissions: { type: "array", items: { type: "string" } } - * }, - * required: ["role"] - * } - * ], - * description: "Extended user with role and permissions" - * }; - * ``` - * - * @example (nested object): - * ```ts - * const addressSchema: ObjectSchema = { - * type: "object", - * properties: { - * street: { type: "string" }, - * city: { type: "string" }, - * state: { type: "string" }, - * zipCode: { type: "string", pattern: "^\\d{5}(-\\d{4})?$" }, - * country: { type: "string", default: "US" } - * }, - * required: ["street", "city", "state", "zipCode"], - * example: { - * street: "123 Main St", - * city: "Anytown", - * state: "CA", - * zipCode: "12345", - * country: "US" - * } - * }; - * ``` - */ -export interface ObjectSchema extends Extension { - /** - * The type of the schema. Must be "object" for object schemas. - * - * This property is required and must be set to "object" to indicate - * that this schema represents structured data with named properties. - * - * @example "object" - */ - type: "object" - - /** - * The properties of the object. The definition is the same as the one from - * JSON Schema, but references the Swagger Schema Object definition instead. - * - * Each property name maps to a schema definition that describes the type - * and validation rules for that property. Properties can be of any type - * supported by Swagger schemas, including primitives, objects, arrays, - * and references. - * - * @example { name: { type: "string" }, age: { type: "integer" } } - * @example { address: { $ref: "#/definitions/Address" } } - */ - properties?: Record // Forward declaration to avoid circular imports - - /** - * A list of required properties. Properties marked as required being true - * MUST be present in the object. - * - * This array contains the names of properties that must be present in - * any valid instance of this object schema. Properties not listed here - * are considered optional. - * - * @example ["name", "email"] - * @example ["id", "type", "createdAt"] - */ - required?: string[] - - /** - * Additional properties for the object. Can be a boolean or a schema. - * The definition is the same as the one from JSON Schema, but references - * the Swagger Schema Object definition instead. - * - * - If true, additional properties of any type are allowed - * - If false, no additional properties are allowed - * - If a schema, additional properties must conform to that schema - * - * @example true - * @example false - * @example { type: "string" } - * @example { $ref: "#/definitions/AdditionalProperty" } - */ - additionalProperties?: boolean | any // Forward declaration to avoid circular imports - - /** - * An array of schemas that this schema must validate against. - * All schemas in the array must be valid for the object to be valid. - * The definition is the same as the one from JSON Schema, but references - * the Swagger Schema Object definition instead. - * - * This enables schema composition and inheritance patterns, allowing - * objects to extend or combine multiple base schemas. - * - * @example [{ $ref: "#/definitions/BaseUser" }, { type: "object", properties: { ... } }] - * @example [{ $ref: "#/definitions/Identifiable" }, { $ref: "#/definitions/Timestamped" }] - */ - allOf?: any[] // Forward declaration to avoid circular imports - - /** - * An object is valid against "maxProperties" if its number of properties is less than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.4.1 | JSON Schema Validation - maxProperties} - * - * @example 10 - * @example 50 - */ - maxProperties?: number - - /** - * An object is valid against "minProperties" if its number of properties is greater than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.4.2 | JSON Schema Validation - minProperties} - * - * @example 1 - * @example 2 - */ - minProperties?: number -} diff --git a/2.0.0/data-types/schema.ts b/2.0.0/data-types/schema.ts deleted file mode 100644 index 489f486..0000000 --- a/2.0.0/data-types/schema.ts +++ /dev/null @@ -1,107 +0,0 @@ -import type { BaseReference } from "../references" -import type { StringSchema } from "./string" -import type { NumberSchema } from "./number" -import type { IntegerSchema } from "./integer" -import type { BooleanSchema } from "./boolean" -import type { FileSchema } from "./file" -import type { ArraySchema } from "./array" -import type { ObjectSchema } from "./object" - -/** - * ----- - * Schema - * ----- - * - * The complete schema type for Swagger 2.0, which includes all possible schema types - * plus Swagger-specific extensions. This is the union type that represents any valid - * schema definition in a Swagger 2.0 specification. - * - * Swagger schemas are based on JSON Schema Draft 4 with Swagger-specific extensions - * and the additional "file" type. They provide comprehensive validation capabilities - * for all data types supported by the Swagger 2.0 specification. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * - * ----- - * Schema Types - * ----- - * - * @key `StringSchema` - String data types with format and validation - * @key `NumberSchema` - Numeric data types (floating-point) - * @key `IntegerSchema` - Integer data types (whole numbers) - * @key `BooleanSchema` - Boolean data types (true/false) - * @key `FileSchema` - File data types (Swagger 2.0 specific) - * @key `ArraySchema` - Array data types with item validation - * @key `ObjectSchema` - Object data types with property definitions - * @key `BaseReference` - JSON Reference to other schema definitions - * - * @note - * All schema types inherit from BaseSchemaProperties and support - * comprehensive validation rules. The "file" type is specific to - * Swagger 2.0 and not part of the JSON Schema specification. - * - * ----- - * Examples - * ----- - * - * @example (string schema): - * ```ts - * const stringSchema: Schema = { - * type: "string", - * format: "email", - * description: "User email address", - * pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" - * }; - * ``` - * - * @example (object schema): - * ```ts - * const userSchema: Schema = { - * type: "object", - * properties: { - * id: { type: "integer", format: "int64" }, - * name: { type: "string" }, - * email: { type: "string", format: "email" } - * }, - * required: ["id", "name", "email"] - * }; - * ``` - * - * @example (array schema): - * ```ts - * const tagsSchema: Schema = { - * type: "array", - * items: { type: "string" }, - * minItems: 1, - * maxItems: 10, - * uniqueItems: true - * }; - * ``` - * - * @example (reference schema): - * ```ts - * const refSchema: Schema = { - * $ref: "#/definitions/User" - * }; - * ``` - * - * @example (file schema): - * ```ts - * const fileSchema: Schema = { - * type: "file", - * description: "Image file to upload" - * }; - * ``` - */ -export type Schema = - | StringSchema - | NumberSchema - | IntegerSchema - | BooleanSchema - | FileSchema - | ArraySchema - | ObjectSchema - | BaseReference diff --git a/2.0.0/data-types/string.ts b/2.0.0/data-types/string.ts deleted file mode 100644 index 0ec4732..0000000 --- a/2.0.0/data-types/string.ts +++ /dev/null @@ -1,215 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * String Schema - * ----- - * - * Schema for string data types in Swagger 2.0. - * - * String schemas represent textual data and support various formats and validation - * rules. They are one of the most commonly used schema types in API specifications, - * used for names, descriptions, identifiers, and other text-based data. - * - * String schemas support a wide range of formats including standard formats like - * email, date, and UUID, as well as custom formats defined by the API provider. - * They also support comprehensive validation through pattern matching, length - * constraints, and enumeration. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "string" for string schemas. - * @key `format` - The extending format for the string type. See Data Type Formats for further details. - * @key `description` - A short description of the string schema. - * @key `title` - A short title for the string schema. - * @key `default` - Declares the default value for the string. - * @key `maxLength` - Maximum length of the string. - * @key `minLength` - Minimum length of the string. - * @key `pattern` - Regular expression pattern the string must match. - * @key `enum` - Array of allowed string values. - * @key `example` - Example string value. - * - * @note - * String schemas include only properties that are valid for string types. - * This ensures type safety and prevents invalid property combinations. - * - * ----- - * Examples - * ----- - * - * @example (email string): - * ```ts - * const emailSchema: StringSchema = { - * type: "string", - * format: "email", - * description: "User email address", - * pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", - * maxLength: 254, - * minLength: 5, - * example: "user@example.com" - * }; - * ``` - * - * @example (date string): - * ```ts - * const dateSchema: StringSchema = { - * type: "string", - * format: "date", - * description: "Date in YYYY-MM-DD format", - * pattern: "^\\d{4}-\\d{2}-\\d{2}$", - * example: "2023-12-25" - * }; - * ``` - * - * @example (enum string): - * ```ts - * const statusSchema: StringSchema = { - * type: "string", - * description: "Order status", - * enum: ["pending", "processing", "shipped", "delivered", "cancelled"], - * default: "pending", - * example: "pending" - * }; - * ``` - * - * @example (custom format string): - * ```ts - * const uuidSchema: StringSchema = { - * type: "string", - * format: "uuid", - * description: "Universally unique identifier", - * pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", - * example: "550e8400-e29b-41d4-a716-446655440000" - * }; - * ``` - */ -export interface StringSchema extends Extension { - /** - * The type of the schema. Must be "string" for string schemas. - * - * This property is required and must be set to "string" to indicate - * that this schema represents string data. - * - * @example "string" - */ - type: "string" - - /** - * The extending format for the previously mentioned type. - * See Swagger 2.0 Data Type Formats for further details. - * - * Formats provide additional semantic information about the data type, - * enabling more precise validation and better tooling support. Swagger 2.0 - * defines several standard formats, but custom formats are also allowed. - * - * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} - * - * @example "int32" - * @example "date" - * @example "email" - * @example "uuid" - */ - format?: string - - /** - * A short description of the schema. GFM syntax can be used for rich text representation. - * - * This description should provide clear information about what the schema - * represents and how it should be used. It's commonly displayed in API - * documentation and code generation tools. - * - * @example "A user object containing basic information" - * @example "Email address in RFC 5322 format" - */ - description?: string - - /** - * A short title for the schema. - * - * The title provides a human-readable name for the schema, often used - * in documentation and UI displays. It should be concise but descriptive. - * - * @example "User" - * @example "Pet" - * @example "Order" - */ - title?: string - - /** - * Declares the value of the schema that the server will use if none is provided. - * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. - * - * This is a Swagger 2.0 specific requirement that differs from JSON Schema. - * The default value must be valid according to the schema's type and constraints. - * - * @example "defaultValue" - * @example 10 - * @example { name: "John", age: 30 } - * @example ["item1", "item2"] - */ - default?: unknown - - /** - * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} - * - * @example ["option1", "option2", "option3"] - * @example ["red", "green", "blue"] - * @example [1, 2, 3, 4, 5] - */ - enum?: unknown[] - - /** - * A free-form property to include an example of an instance for this schema. - * - * Examples help developers understand how to use the schema and what kind - * of data is expected. They are commonly used by documentation generators - * and API testing tools. - * - * @example { name: "Puma", id: 1 } - * @example "example string value" - * @example 42 - * @example ["item1", "item2"] - */ - example?: unknown - - /** - * A string is valid against "maxLength" if its length is less than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 | JSON Schema Validation - maxLength} - * - * @example 100 - * @example 255 - */ - maxLength?: number - - /** - * A string is valid against "minLength" if its length is greater than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 | JSON Schema Validation - minLength} - * - * @example 1 - * @example 8 - */ - minLength?: number - - /** - * A string is valid against "pattern" if the regular expression matches the string successfully. - * The regular expression syntax follows ECMA 262. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 | JSON Schema Validation - pattern} - * @see {@link https://www.ecma-international.org/ecma-262/5.1/#sec-15.10 | ECMA 262 Regular Expression Syntax} - * - * @example "^[a-zA-Z0-9]+$" - * @example "^\\d{4}-\\d{2}-\\d{2}$" - */ - pattern?: string -} diff --git a/2.0.0/index.ts b/2.0.0/index.ts deleted file mode 100644 index c71bc01..0000000 --- a/2.0.0/index.ts +++ /dev/null @@ -1,107 +0,0 @@ -// Centralized exports for OpenAPI 2.0 types -// This file serves as the main entry point for all OpenAPI 2.0 type definitions - -// Export the main specification type -export type { Specification } from "./spec" - -// Re-export all types for convenience -export type { - // Core types - Extension, -} from "./extensions" - -export type { - // Info types - Info, - Contact, - License, -} from "./info" - -export type { - // Path types - PathItemObject, - Operation, - Parameter, - Response, - Header, - Items, -} from "./paths" - -export type { - // Schema types - Schema, - SwaggerSchema, - XML, - Definitions, - ParametersDefinitions, - ResponsesDefinitions, -} from "./schema" - -export type { - // Security types - SecurityScheme, - SecurityRequirement, - Scopes, - SecurityDefinitions, -} from "./security" - -export type { - // Utility types - Tag, -} from "./tags" - -export type { - ExternalDocumentation, -} from "./external-documentation" - -export type { - Example, -} from "./example" - -export type { - Paths, -} from "./paths" - -// Re-export data types -export type { - // Base schema - BaseSchemaProperties, -} from "./data-types/base-schema" - -export type { - // Individual schema types - StringSchema, - NumberSchema, - IntegerSchema, - BooleanSchema, - FileSchema, - ArraySchema, - ObjectSchema, -} from "./data-types" - -export type { - // XML Object - XMLObject, -} from "./xml" - -export type { - // Swagger Schema with Extensions - SwaggerSchemaWithExtensions, -} from "./schema" - -export type { - // References - BaseReference, - Reference, -} from "./references" - -// All supporting types are now defined in their respective modules: -// - spec.ts: Specification (main root type) -// - info.ts: Info, Contact, License -// - paths.ts: PathItemObject, Operation, Parameter, Response, Header, Items -// - schema.ts: Schema, SwaggerSchema, SwaggerSchemaWithExtensions, XML, Definitions, ParametersDefinitions, ResponsesDefinitions -// - security.ts: SecurityScheme, SecurityRequirement, Scopes, SecurityDefinitions -// - shallow.ts: Tag, ExternalDocumentation, Reference, Example, Paths -// - data-types/: All individual schema types -// - xml-object.ts: XMLObject -// - references.ts: BaseReference, Reference \ No newline at end of file diff --git a/2.0.0/info.ts b/2.0.0/info.ts deleted file mode 100644 index 07a18ad..0000000 --- a/2.0.0/info.ts +++ /dev/null @@ -1,205 +0,0 @@ -import type { Extension } from "./extensions" -import type { ExternalDocumentation } from "./externalDocs" - -/** - * Info Object - * - * The object provides metadata about the API. The metadata can be used by the clients - * if needed, and can be presented in the Swagger-UI for convenience. - * - * @see https://swagger.io/specification/v2/#info-object - * @example - * ```typescript - * const info: Info = { - * title: "Swagger Sample App", - * description: "This is a sample server Petstore server.", - * termsOfService: "http://swagger.io/terms/", - * contact: { - * name: "API Support", - * url: "http://www.swagger.io/support", - * email: "support@swagger.io" - * }, - * license: { - * name: "Apache 2.0", - * url: "http://www.apache.org/licenses/LICENSE-2.0.html" - * }, - * version: "1.0.1" - * } - * ``` - */ -export interface Info extends Extension { - /** - * The title of the application. This field is required. - * - * @example "Swagger Sample App" - * @example "My API" - */ - title: string - - /** - * A short description of the application. GFM syntax can be used for rich text representation. - * - * @example "This is a sample server Petstore server." - * @example "A comprehensive API for managing user data" - */ - description?: string - - /** - * The Terms of Service for the API. - * - * @example "http://swagger.io/terms/" - * @example "https://example.com/terms" - */ - termsOfService?: string - - /** - * The contact information for the exposed API. - * - * @example { name: "API Support", email: "support@example.com" } - */ - contact?: Contact - - /** - * The license information for the exposed API. - * - * @example { name: "Apache 2.0", url: "http://www.apache.org/licenses/LICENSE-2.0.html" } - */ - license?: License - - /** - * Provides the version of the application API (not to be confused with the specification version). - * This field is required. - * - * @example "1.0.1" - * @example "2.0.0" - */ - version: string -} - -/** - * Contact Object - * - * Contact information for the exposed API. - * - * @see https://swagger.io/specification/v2/#contact-object - * @example - * ```typescript - * const contact: Contact = { - * name: "API Support", - * url: "http://www.swagger.io/support", - * email: "support@swagger.io" - * } - * ``` - */ -export interface Contact extends Extension { - /** - * The identifying name of the contact person/organization. - * - * @example "API Support" - * @example "John Doe" - */ - name?: string - - /** - * The URL pointing to the contact information. MUST be in the format of a URL. - * - * @example "http://www.swagger.io/support" - * @example "https://example.com/contact" - */ - url?: string - - /** - * The email address of the contact person/organization. MUST be in the format of an email address. - * - * @example "support@swagger.io" - * @example "contact@example.com" - */ - email?: string -} - -/** - * ----- - * License Object - * ----- - * - * License information for the exposed API. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#license-object | Swagger 2.0 License} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Required The license name used for the API - * @key `url` - Optional A URL to the license used for the API - * @key `x-${string}` - Specification Extensions - * - * @note - * The `name` field is required. The `url` field is optional but recommended. - * - * ----- - * Examples - * ----- - * - * @example (MIT License): - * ```ts - * const license: License = { - * name: "MIT License", - * url: "https://opensource.org/license/mit/" - * }; - * ``` - * - * @example (Apache 2.0): - * ```ts - * const license: License = { - * name: "Apache License 2.0", - * url: "https://www.apache.org/licenses/LICENSE-2.0" - * }; - * ``` - * - * @example (custom license): - * ```ts - * const license: License = { - * name: "Proprietary Foo License", - * url: "https://example.com/licenses/foo-1.0" - * }; - * ``` - * - * @example (license without URL): - * ```ts - * const license: License = { - * name: "Custom License" - * }; - * ``` - * - * @example (license with extensions): - * ```ts - * const license: License = { - * name: "MIT License", - * url: "https://opensource.org/license/mit/", - * "x-custom": "value", - * "x-internal": true - * }; - * ``` - */ -export interface License extends Extension { - /** - * The license name used for the API. This field is required. - * - * @example "MIT License" - * @example "Apache License 2.0" - * @example "Proprietary Foo License" - */ - name: string - - /** - * A URL to the license used for the API. MUST be in the format of a URL. - * - * @example "https://opensource.org/license/mit/" - * @example "https://www.apache.org/licenses/LICENSE-2.0" - * @example "https://example.com/licenses/foo-1.0" - */ - url?: string -} \ No newline at end of file diff --git a/2.0.0/paths.ts b/2.0.0/paths.ts deleted file mode 100644 index 7cef07b..0000000 --- a/2.0.0/paths.ts +++ /dev/null @@ -1,988 +0,0 @@ -import type { BaseReference } from "./references" -import type { Extension } from "./extensions" -import type { ExternalDocumentation } from "./external-documentation" -import type { SwaggerSchema } from "./data-types" - -/** - * Path Item Object - * - * Describes the operations available on a single path. A Path Item may be empty, - * due to ACL constraints. The path itself is still exposed to the documentation - * viewer but they will not know which operations and parameters are available. - * - * @see https://swagger.io/specification/v2/#path-item-object - * @example - * ```typescript - * const pathItem: PathItemObject = { - * get: { - * summary: "Get users", - * operationId: "getUsers", - * responses: { - * "200": { - * description: "List of users", - * schema: { type: "array", items: { $ref: "#/definitions/User" } } - * } - * } - * }, - * post: { - * summary: "Create user", - * operationId: "createUser", - * parameters: [ - * { - * name: "user", - * in: "body", - * schema: { $ref: "#/definitions/User" } - * } - * ], - * responses: { - * "201": { - * description: "User created", - * schema: { $ref: "#/definitions/User" } - * } - * } - * }, - * parameters: [ - * { - * name: "limit", - * in: "query", - * type: "integer", - * description: "Maximum number of items to return" - * } - * ] - * } - * ``` - */ -export type PathItemObject = - | ({ - /** - * A definition of a GET operation on this path. - * - * @example { summary: "Get users", responses: { "200": { description: "Success" } } } - */ - get?: Operation - - /** - * A definition of a PUT operation on this path. - * - * @example { summary: "Update user", responses: { "200": { description: "Success" } } } - */ - put?: Operation - - /** - * A definition of a POST operation on this path. - * - * @example { summary: "Create user", responses: { "201": { description: "Created" } } } - */ - post?: Operation - - /** - * A definition of a DELETE operation on this path. - * - * @example { summary: "Delete user", responses: { "204": { description: "No Content" } } } - */ - delete?: Operation - - /** - * A definition of an OPTIONS operation on this path. - * - * @example { summary: "Get options", responses: { "200": { description: "Options" } } } - */ - options?: Operation - - /** - * A definition of a HEAD operation on this path. - * - * @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } } - */ - head?: Operation - - /** - * A definition of a PATCH operation on this path. - * - * @example { summary: "Partially update user", responses: { "200": { description: "Success" } } } - */ - patch?: Operation - - /** - * A list of parameters that are applicable for all the operations described - * under this path. These parameters can be overridden at the operation level, - * but cannot be removed there. The list MUST NOT include duplicated parameters. - * A unique parameter is defined by a combination of a name and location. - * - * @example [{ name: "limit", in: "query", type: "integer" }] - */ - parameters?: Array - } & Extension) - | BaseReference - -/** - * Operation Object - * - * Describes a single API operation on a path. A unique operation is defined - * by a combination of a path and an HTTP method. - * - * @see https://swagger.io/specification/v2/#operation-object - * @example - * ```typescript - * const operation: Operation = { - * tags: ["users"], - * summary: "Get user by ID", - * description: "Retrieves a specific user by their unique identifier", - * operationId: "getUserById", - * consumes: ["application/json"], - * produces: ["application/json"], - * parameters: [ - * { - * name: "id", - * in: "path", - * required: true, - * type: "string", - * description: "The user ID" - * } - * ], - * responses: { - * "200": { - * description: "User found", - * schema: { $ref: "#/definitions/User" } - * }, - * "404": { - * description: "User not found" - * } - * }, - * deprecated: false, - * security: [{ "api_key": [] }] - * } - * ``` - */ -export interface Operation extends Extension { - /** - * A list of tags for API documentation control. Tags can be used for logical - * grouping of operations by resources or any other qualifier. - * - * @example ["users", "authentication"] - * @example ["pets"] - */ - tags?: string[] - - /** - * A short summary of what the operation does. For maximum readability in - * swagger-ui, this field SHOULD be less than 120 characters. - * - * @example "Get user by ID" - * @example "Create a new pet" - */ - summary?: string - - /** - * A verbose explanation of the operation behavior. GFM syntax can be used - * for rich text representation. - * - * @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information." - */ - description?: string - - /** - * Additional external documentation for this operation. - * - * @example { description: "Find out more about this operation", url: "https://example.com/docs" } - */ - externalDocs?: ExternalDocumentation - - /** - * Unique string used to identify the operation. The id MUST be unique among - * all operations described in the API. Tools and libraries MAY use the - * operationId to uniquely identify an operation, therefore, it is recommended - * to follow common programming naming conventions. - * - * @example "getUserById" - * @example "createPet" - */ - operationId?: string - - /** - * A list of MIME types the operation can consume. This overrides the consumes - * definition at the Swagger Object level. An empty value MAY be used to clear - * the global definition. Value MUST be as described under Mime Types. - * - * @example ["application/json"] - * @example ["application/xml", "application/json"] - */ - consumes?: string[] - - /** - * A list of MIME types the operation can produce. This overrides the produces - * definition at the Swagger Object level. An empty value MAY be used to clear - * the global definition. Value MUST be as described under Mime Types. - * - * @example ["application/json"] - * @example ["application/xml", "application/json"] - */ - produces?: string[] - - /** - * A list of parameters that are applicable for this operation. If a parameter - * is already defined at the Path Item, the new definition will override it - * but can never remove it. The list MUST NOT include duplicated parameters. - * A unique parameter is defined by a combination of a name and location. - * - * @example [{ name: "id", in: "path", required: true, type: "string" }] - */ - parameters?: Array - - /** - * The list of possible responses as they are returned from executing this operation. - * This field MUST be present and MUST contain at least one response. - * - * @example { "200": { description: "Success", schema: { type: "object" } } } - */ - responses: Record - - /** - * The transfer protocol for the operation. Values MUST be from the list: - * "http", "https", "ws", "wss". The value overrides the Swagger Object - * schemes definition. - * - * @example ["https", "http"] - * @example ["wss"] - */ - schemes?: Array<"http" | "https" | "ws" | "wss"> - - /** - * Declares this operation to be deprecated. Usage of the declared operation - * should be refrained. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - /** - * A declaration of which security schemes are applied for this operation. - * The list of values describes alternative security schemes that can be used - * (that is, there is a logical OR between the security requirements). - * This definition overrides any declared top-level security. To remove a - * top-level security declaration, an empty array can be used. - * - * @example [{ "api_key": [] }] - * @example [{ "oauth2": ["read", "write"] }] - */ - security?: Array> -} - -/** - * Parameter Object - * - * Describes a single operation parameter. A unique parameter is defined by a - * combination of a name and location. - * - * @see https://swagger.io/specification/v2/#parameter-object - * @example - * ```typescript - * // Query parameter - * const queryParam: Parameter = { - * name: "limit", - * in: "query", - * description: "Maximum number of items to return", - * required: false, - * type: "integer", - * format: "int32" - * } - * - * // Path parameter - * const pathParam: Parameter = { - * name: "id", - * in: "path", - * description: "The user ID", - * required: true, - * type: "string" - * } - * - * // Body parameter - * const bodyParam: Parameter = { - * name: "user", - * in: "body", - * description: "User object to create", - * required: true, - * schema: { $ref: "#/definitions/User" } - * } - * ``` - */ -export interface Parameter extends Extension { - /** - * The name of the parameter. Parameter names are case sensitive. - * - If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object - * - For all other cases, the name corresponds to the parameter name used by the in property - * - * @example "id" - * @example "limit" - * @example "user" - */ - name: string - - /** - * The location of the parameter. Possible values are "query", "header", "path", "formData" or "body". - * - * - **query**: Parameters that are appended to the URL. For example, in `/users?role=admin`, the role query parameter has the value admin. - * - **header**: Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive. - * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. - * - **formData**: Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded or multipart/form-data is used as the content type of the request. - * - **body**: The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. - * - * @example "query" - * @example "path" - * @example "body" - */ - in: "query" | "header" | "path" | "formData" | "body" - - /** - * A brief description of the parameter. This could contain examples of use. - * GFM syntax can be used for rich text representation. - * - * @example "The user ID" - * @example "Maximum number of items to return (default: 10)" - */ - description?: string - - /** - * Determines whether this parameter is mandatory. If the parameter is in "path", - * this property is required and its value MUST be true. Otherwise, the property - * MAY be included and its default value is false. - * - * @default false - * @example true - */ - required?: boolean - - /** - * The type of the parameter. Since the parameter is not located at the request body, - * it is limited to simple types (that is, not an object). The value MUST be one of - * "string", "number", "integer", "boolean", "array" or "file". If type is "file", - * the consumes MUST be either "multipart/form-data", "application/x-www-form-urlencoded" - * or both and the parameter MUST be in "formData". - * - * @example "string" - * @example "integer" - * @example "array" - */ - type?: string - - /** - * The extending format for the previously mentioned type. See Data Type Formats - * for further details. - * - * @example "int32" - * @example "date" - * @example "email" - */ - format?: string - - /** - * Sets the ability to pass empty-valued parameters. This is valid only for either - * query or formData parameters and allows you to send a parameter with a name only - * or an empty value. Default value is false. - * - * @default false - * @example true - */ - allowEmptyValue?: boolean - - /** - * The schema defining the type used for the body parameter. This property is - * only applicable for parameters with in: "body". - * - * @example { $ref: "#/definitions/User" } - * @example { type: "object", properties: { name: { type: "string" } } } - */ - schema?: SwaggerSchema - - /** - * Required if type is "array". Describes the type of items in the array. - * - * @example { type: "string" } - * @example { type: "integer", format: "int32" } - */ - items?: Items - - /** - * Determines the format of the array if type array is used. Possible values are: - * - csv: comma separated values foo,bar - * - ssv: space separated values foo bar - * - tsv: tab separated values foo\tbar - * - pipes: pipe separated values foo|bar - * - multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz - * - * @default "csv" - * @example "multi" - */ - collectionFormat?: "csv" | "ssv" | "tsv" | "pipes" | "multi" - - /** - * Declares the value of the parameter that the server will use if none is provided. - * This value MUST conform to the defined type for this parameter. - * - * @example "defaultValue" - * @example 10 - */ - default?: unknown - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 - * - * @example 100 - */ - maximum?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 - * - * @example false - */ - exclusiveMaximum?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 - * - * @example 0 - */ - minimum?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 - * - * @example false - */ - exclusiveMinimum?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 - * - * @example 100 - */ - maxLength?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 - * - * @example 1 - */ - minLength?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 - * - * @example "^[a-zA-Z0-9]+$" - */ - pattern?: string - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 - * - * @example 10 - */ - maxItems?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 - * - * @example 1 - */ - minItems?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 - * - * @example true - */ - uniqueItems?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 - * - * @example ["option1", "option2", "option3"] - */ - enum?: unknown[] - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 - * - * @example 2 - */ - multipleOf?: number -} - -/** - * Paths Object - * - * Holds the relative paths to the individual endpoints. The path is appended to the - * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints. - * - * @see https://swagger.io/specification/v2/#paths-object - * @example - * ```typescript - * const paths: Paths = { - * "/pets": { - * "get": { - * "description": "Returns all pets from the system that the user has access to", - * "produces": ["application/json"], - * "responses": { - * "200": { - * "description": "A list of pets.", - * "schema": { - * "type": "array", - * "items": { - * "$ref": "#/definitions/pet" - * } - * } - * } - * } - * } - * } - * } - * ``` - */ -export type Paths = Record - -/** - * Items Object - * - * A limited subset of JSON-Schema's items object. It is used by parameter definitions - * that are not located in "body". - * - * @see https://swagger.io/specification/v2/#items-object - * @example - * ```typescript - * const items: Items = { - * type: "string", - * minLength: 2 - * } - * ``` - */ -export interface Items extends Extension { - /** - * The internal type of the array. The value MUST be one of "string", "number", - * "integer", "boolean", or "array". Files and models are not allowed. - * - * @example "string" - * @example "integer" - * @example "array" - */ - type: string - - /** - * The extending format for the previously mentioned type. See Data Type Formats - * for further details. - * - * @example "int32" - * @example "date" - * @example "email" - */ - format?: string - - /** - * Required if type is "array". Describes the type of items in the array. - * - * @example { type: "string" } - * @example { type: "integer", format: "int32" } - */ - items?: Items - - /** - * Determines the format of the array if type array is used. Possible values are: - * - csv: comma separated values foo,bar - * - ssv: space separated values foo bar - * - tsv: tab separated values foo\tbar - * - pipes: pipe separated values foo|bar - * - * @default "csv" - * @example "multi" - */ - collectionFormat?: "csv" | "ssv" | "tsv" | "pipes" - - /** - * Declares the value of the item that the server will use if none is provided. - * This value MUST conform to the defined type for the data type. - * - * @example "defaultValue" - * @example 10 - */ - default?: unknown - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 - * - * @example 100 - */ - maximum?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 - * - * @example false - */ - exclusiveMaximum?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 - * - * @example 0 - */ - minimum?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 - * - * @example false - */ - exclusiveMinimum?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 - * - * @example 100 - */ - maxLength?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 - * - * @example 1 - */ - minLength?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 - * - * @example "^[a-zA-Z0-9]+$" - */ - pattern?: string - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 - * - * @example 10 - */ - maxItems?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 - * - * @example 1 - */ - minItems?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 - * - * @example true - */ - uniqueItems?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 - * - * @example ["option1", "option2", "option3"] - */ - enum?: unknown[] - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 - * - * @example 2 - */ - multipleOf?: number -} - -/** - * Paths Object - * - * Holds the relative paths to the individual endpoints. The path is appended to the - * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints. - * - * @see https://swagger.io/specification/v2/#paths-object - * @example - * ```typescript - * const paths: Paths = { - * "/pets": { - * "get": { - * "description": "Returns all pets from the system that the user has access to", - * "produces": ["application/json"], - * "responses": { - * "200": { - * "description": "A list of pets.", - * "schema": { - * "type": "array", - * "items": { - * "$ref": "#/definitions/pet" - * } - * } - * } - * } - * } - * } - * } - * ``` - */ - -/** - * Response Object - * - * Describes a single response from an API Operation. A container for the expected - * responses of an operation. The container maps a HTTP response code to the expected - * response. It is not expected from the documentation to necessarily cover all - * possible HTTP response codes because they may not be known in advance. However, - * it is expected from the documentation to cover a successful operation response - * and any known errors. - * - * @see https://swagger.io/specification/v2/#response-object - * @example - * ```typescript - * const response: Response = { - * description: "User successfully retrieved", - * schema: { $ref: "#/definitions/User" }, - * headers: { - * "X-RateLimit-Limit": { - * type: "integer", - * description: "Rate limit for the current period" - * } - * }, - * examples: { - * "application/json": { - * id: 1, - * name: "John Doe", - * email: "john@example.com" - * } - * } - * } - * ``` - */ -export interface Response extends Extension { - /** - * A short description of the response. GFM syntax can be used for rich text representation. - * This field is required. - * - * @example "User successfully retrieved" - * @example "Bad request - invalid input parameters" - * @example "Internal server error" - */ - description: string - - /** - * A definition of the response structure. It can be a primitive, an array or an object. - * If this field does not exist, it means no content is returned as part of the response. - * As an extension to the Schema Object, its root type value may also be "file". - * This SHOULD be accompanied by a relevant produces mime-type. - * - * @example { $ref: "#/definitions/User" } - * @example { type: "array", items: { $ref: "#/definitions/User" } } - * @example { type: "string" } - */ - schema?: SwaggerSchema - - /** - * A list of headers that are sent with the response. - * - * @example { "X-RateLimit-Limit": { type: "integer", description: "Rate limit" } } - */ - headers?: Record - - /** - * An example of the response message. This property is not part of the OpenAPI - * specification but is commonly used by tools to provide example responses. - * - * @example { "application/json": { id: 1, name: "John Doe" } } - */ - examples?: Record -} - -/** - * Header Object - * - * Describes a single header parameter. A list of all headers that are sent with - * the response. The name is used to refer to the respective header definition. - * The value of the header is of type string. - * - * @see https://swagger.io/specification/v2/#header-object - * @example - * ```typescript - * const header: Header = { - * description: "Rate limit for the current period", - * type: "integer", - * format: "int32" - * } - * ``` - */ -export interface Header extends Extension { - /** - * A brief description of the header. GFM syntax can be used for rich text representation. - * - * @example "Rate limit for the current period" - * @example "Content type of the response" - */ - description?: string - - /** - * The type of the object. The value MUST be one of "string", "number", "integer", - * "boolean", or "array". - * This field is required. - * - * @example "string" - * @example "integer" - * @example "array" - */ - type: string - - /** - * The extending format for the previously mentioned type. See Data Type Formats - * for further details. - * - * @example "int32" - * @example "date" - * @example "email" - */ - format?: string - - /** - * Required if type is "array". Describes the type of items in the array. - * - * @example { type: "string" } - * @example { type: "integer", format: "int32" } - */ - items?: Items - - /** - * Determines the format of the array if type array is used. Possible values are: - * - csv: comma separated values foo,bar - * - ssv: space separated values foo bar - * - tsv: tab separated values foo\tbar - * - pipes: pipe separated values foo|bar - * - * @default "csv" - * @example "multi" - */ - collectionFormat?: "csv" | "ssv" | "tsv" | "pipes" - - /** - * Declares the value of the header that the server will use if none is provided. - * This value MUST conform to the defined type for the header. - * - * @example "defaultValue" - * @example 10 - */ - default?: unknown - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 - * - * @example 100 - */ - maximum?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 - * - * @example false - */ - exclusiveMaximum?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 - * - * @example 0 - */ - minimum?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 - * - * @example false - */ - exclusiveMinimum?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 - * - * @example 100 - */ - maxLength?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 - * - * @example 1 - */ - minLength?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 - * - * @example "^[a-zA-Z0-9]+$" - */ - pattern?: string - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 - * - * @example 10 - */ - maxItems?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 - * - * @example 1 - */ - minItems?: number - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 - * - * @example true - */ - uniqueItems?: boolean - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 - * - * @example ["option1", "option2", "option3"] - */ - enum?: unknown[] - - /** - * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 - * - * @example 2 - */ - multipleOf?: number -} - -/** - * Paths Object - * - * Holds the relative paths to the individual endpoints. The path is appended to the - * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints. - * - * @see https://swagger.io/specification/v2/#paths-object - * @example - * ```typescript - * const paths: Paths = { - * "/pets": { - * "get": { - * "description": "Returns all pets from the system that the user has access to", - * "produces": ["application/json"], - * "responses": { - * "200": { - * "description": "A list of pets.", - * "schema": { - * "type": "array", - * "items": { - * "$ref": "#/definitions/pet" - * } - * } - * } - * } - * } - * } - * } - * ``` - */ -export type Paths = Record diff --git a/2.0.0/schema.ts b/2.0.0/schema.ts deleted file mode 100644 index 66043ac..0000000 --- a/2.0.0/schema.ts +++ /dev/null @@ -1,378 +0,0 @@ -import type { - StringSchema, - NumberSchema, - IntegerSchema, - BooleanSchema, - ArraySchema, - ObjectSchema, - FileSchema, - SwaggerSchema as BaseSwaggerSchema, - BaseSchemaProperties, -} from "./data-types" -import type { BaseReference } from "./references" -import type { XMLObject } from "./xml" -import type { ExternalDocumentation } from "./externalDocs" - -/** - * Schema Object (Swagger 2.0) - * - * The Schema Object allows the definition of input and output data types. - * These types can be objects, but also primitives and arrays. This object - * is a subset of JSON Schema Specification Draft 4 and uses the same - * formatting rules (sections 9-11). - * - * In Swagger 2.0, this is a limited subset of JSON Schema. Here we model it - * as a union of known schema atoms or a reference to a definition. - * - * @see https://swagger.io/specification/v2/#schema-object - * @example - * ```typescript - * // String schema - * const stringSchema: Schema = { - * type: "string", - * minLength: 1, - * maxLength: 100 - * } - * - * // Object schema - * const objectSchema: Schema = { - * type: "object", - * properties: { - * name: { type: "string" }, - * age: { type: "integer" } - * }, - * required: ["name"] - * } - * - * // Reference to a definition - * const refSchema: Schema = { - * $ref: "#/definitions/User" - * } - * ``` - */ -export type Schema = BaseSwaggerSchema - -/** - * XML Object - * - * A metadata object that allows for more fine-tuned XML model definitions. - * When using arrays, XML element names are not inferred (for singular/plural forms) - * and the name property should be used to add that information. - * - * @see https://swagger.io/specification/v2/#xml-object - * @example - * ```typescript - * const xml: XML = { - * name: "animal", - * namespace: "http://example.com/schema/sample", - * prefix: "sample", - * attribute: false, - * wrapped: true - * } - * ``` - */ -/** - * ----- - * Swagger Schema with Extensions - * ----- - * - * Extended schema that includes Swagger 2.0 specific properties beyond JSON Schema. - * This interface combines the base schema properties with Swagger-specific extensions - * that provide additional functionality for API documentation and validation. - * - * Swagger 2.0 extends JSON Schema with several additional properties that are - * specific to API documentation needs, including polymorphism support, read-only - * properties, XML representation metadata, and external documentation references. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `discriminator` - Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. - * @key `readOnly` - Relevant only for Schema "properties" definitions. Declares the property as "read only". - * @key `xml` - This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property. - * @key `externalDocs` - Additional external documentation for this schema. - * - * @note - * All Swagger-specific extension fields are optional. The `discriminator` field - * is used for polymorphism and must be defined in the schema and included in - * the required property list when used. - * - * ----- - * Examples - * ----- - * - * @example (schema with discriminator): - * ```ts - * const polymorphicSchema: SwaggerSchemaWithExtensions = { - * type: "object", - * discriminator: "petType", - * properties: { - * name: { type: "string" }, - * petType: { type: "string" } - * }, - * required: ["name", "petType"] - * }; - * ``` - * - * @example (read-only property): - * ```ts - * const readOnlySchema: SwaggerSchemaWithExtensions = { - * type: "object", - * properties: { - * id: { type: "integer", readOnly: true }, - * name: { type: "string" }, - * createdAt: { type: "string", format: "date-time", readOnly: true } - * }, - * required: ["name"] - * }; - * ``` - * - * @example (schema with XML metadata): - * ```ts - * const xmlSchema: SwaggerSchemaWithExtensions = { - * type: "object", - * properties: { - * id: { - * type: "integer", - * xml: { attribute: true } - * }, - * name: { - * type: "string", - * xml: { - * name: "personName", - * namespace: "http://example.com/schema", - * prefix: "ex" - * } - * } - * } - * }; - * ``` - * - * @example (schema with external docs): - * ```ts - * const documentedSchema: SwaggerSchemaWithExtensions = { - * type: "object", - * properties: { - * data: { type: "string" } - * }, - * externalDocs: { - * description: "Find out more about this schema", - * url: "https://example.com/docs/schema" - * } - * }; - * ``` - * - * @example (complete schema with all extensions): - * ```ts - * const completeSchema: SwaggerSchemaWithExtensions = { - * type: "object", - * discriminator: "type", - * properties: { - * id: { type: "integer", readOnly: true }, - * type: { type: "string" }, - * data: { - * type: "string", - * xml: { name: "content" } - * } - * }, - * required: ["type"], - * externalDocs: { - * description: "Complete schema documentation", - * url: "https://docs.example.com/schema" - * } - * }; - * ``` - */ -export interface SwaggerSchemaWithExtensions extends BaseSchemaProperties { - // String-specific properties - maxLength?: number - minLength?: number - pattern?: string - - // Number/Integer-specific properties - multipleOf?: number - maximum?: number - exclusiveMaximum?: boolean - minimum?: number - exclusiveMinimum?: boolean - - // Array-specific properties - items?: SwaggerSchema | BaseReference - maxItems?: number - minItems?: number - uniqueItems?: boolean - - // Object-specific properties - properties?: Record - required?: string[] - additionalProperties?: boolean | SwaggerSchema | BaseReference - allOf?: (SwaggerSchema | BaseReference)[] - maxProperties?: number - minProperties?: number - - // Swagger-specific extensions - /** - * Adds support for polymorphism. The discriminator is the schema property name - * that is used to differentiate between other schema that inherit this schema. - * The property name used MUST be defined at this schema and it MUST be in the - * required property list. When used, the value MUST be the name of this schema - * or any schema that inherits it. - * - * @example "petType" - * @example "type" - * @example "category" - */ - discriminator?: string - - /** - * Relevant only for Schema "properties" definitions. Declares the property as "read only". - * This means that it MAY be sent as part of a response but MUST NOT be sent as part - * of the request. Properties marked as readOnly being true SHOULD NOT be in the - * required list of the defined schema. Default value is false. - * - * @default false - * @example true - * @example false - */ - readOnly?: boolean - - /** - * This MAY be used only on properties schemas. It has no effect on root schemas. - * Adds Additional metadata to describe the XML representation format of this property. - * - * @example { name: "animal", wrapped: true } - * @example { attribute: true } - * @example { namespace: "http://example.com/schema", prefix: "ex" } - */ - xml?: XMLObject - - /** - * Additional external documentation for this schema. - * - * @example { description: "Find out more about this schema", url: "https://example.com/docs" } - * @example { description: "Schema reference guide", url: "https://docs.example.com/schema" } - */ - externalDocs?: ExternalDocumentation -} - -/** - * Extended Schema Object that includes Swagger 2.0 specific properties - * This combines the base Schema types with Swagger-specific extensions - */ -export type SwaggerSchema = SwaggerSchemaWithExtensions - -/** - * XML Object - * - * A metadata object that allows for more fine-tuned XML model definitions. - * When using arrays, XML element names are not inferred (for singular/plural forms) - * and the name property should be used to add that information. - * - * @see https://swagger.io/specification/v2/#xml-object - */ -export type XML = XMLObject - -/** - * Definitions Object - * - * An object to hold data types that can be consumed and produced by operations. - * These data types can be primitives, arrays or models. - * - * @see https://swagger.io/specification/v2/#definitions-object - * @example - * ```typescript - * const definitions: Definitions = { - * "Category": { - * "type": "object", - * "properties": { - * "id": { - * "type": "integer", - * "format": "int64" - * }, - * "name": { - * "type": "string" - * } - * } - * }, - * "Tag": { - * "type": "object", - * "properties": { - * "id": { - * "type": "integer", - * "format": "int64" - * }, - * "name": { - * "type": "string" - * } - * } - * } - * } - * ``` - */ -export type Definitions = Record - -/** - * Parameters Definitions Object - * - * An object to hold parameters to be reused across operations. Parameter definitions - * can be referenced to the ones defined here. This does not define global operation parameters. - * - * @see https://swagger.io/specification/v2/#parameters-definitions-object - * @example - * ```typescript - * const parameters: ParametersDefinitions = { - * "skipParam": { - * "name": "skip", - * "in": "query", - * "description": "number of items to skip", - * "required": true, - * "type": "integer", - * "format": "int32" - * }, - * "limitParam": { - * "name": "limit", - * "in": "query", - * "description": "max records to return", - * "required": true, - * "type": "integer", - * "format": "int32" - * } - * } - * ``` - */ -export type ParametersDefinitions = Record - -/** - * Responses Definitions Object - * - * An object to hold responses to be reused across operations. Response definitions - * can be referenced to the ones defined here. This does not define global operation responses. - * - * @see https://swagger.io/specification/v2/#responses-definitions-object - * @example - * ```typescript - * const responses: ResponsesDefinitions = { - * "NotFound": { - * "description": "Entity not found." - * }, - * "IllegalInput": { - * "description": "Illegal input for operation." - * }, - * "GeneralError": { - * "description": "General Error", - * "schema": { - * "$ref": "#/definitions/GeneralError" - * } - * } - * } - * ``` - */ -export type ResponsesDefinitions = Record - -// Re-export types from paths.ts to avoid circular dependencies -import type { Parameter, Response } from "./paths" diff --git a/2.0.0/security.ts b/2.0.0/security.ts deleted file mode 100644 index 126b131..0000000 --- a/2.0.0/security.ts +++ /dev/null @@ -1,216 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * Security Scheme Object - * - * Defines a security scheme that can be used by the operations. Supported schemes - * are basic authentication, an API key (either as a header or as a query parameter) - * and OAuth2's common flows (implicit, password, application and access code). - * - * @see https://swagger.io/specification/v2/#security-scheme-object - * @example - * ```typescript - * // API Key authentication - * const apiKeyScheme: SecurityScheme = { - * type: "apiKey", - * name: "X-API-Key", - * in: "header", - * description: "API key for authentication" - * } - * - * // OAuth2 with authorization code flow - * const oauth2Scheme: SecurityScheme = { - * type: "oauth2", - * flow: "accessCode", - * authorizationUrl: "https://example.com/oauth/authorize", - * tokenUrl: "https://example.com/oauth/token", - * scopes: { - * "read": "Read access to resources", - * "write": "Write access to resources" - * } - * } - * - * // Basic authentication - * const basicScheme: SecurityScheme = { - * type: "basic", - * description: "HTTP Basic Authentication" - * } - * ``` - */ -export interface SecurityScheme extends Extension { - /** - * The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2". - * This field is required. - * - * - **basic**: Basic HTTP authentication - * - **apiKey**: API key authentication (header or query parameter) - * - **oauth2**: OAuth 2.0 authentication - * - * @example "apiKey" - * @example "oauth2" - * @example "basic" - */ - type: "basic" | "apiKey" | "oauth2" - - /** - * A short description for security scheme. GFM syntax can be used for rich text representation. - * - * @example "API key for authentication" - * @example "OAuth 2.0 with authorization code flow" - */ - description?: string - - /** - * The name of the header or query parameter to be used. This field is required - * for apiKey type and applies to apiKey type only. - * - * @example "X-API-Key" - * @example "Authorization" - */ - name?: string - - /** - * The location of the API key. This field is required for apiKey type and - * applies to apiKey type only. Valid values are "query" or "header". - * - * @example "header" - * @example "query" - */ - in?: "query" | "header" - - /** - * The flow used by the OAuth2 security scheme. This field is required for - * oauth2 type and applies to oauth2 type only. Valid values are "implicit", - * "password", "application" or "accessCode". - * - * - **implicit**: Implicit flow - * - **password**: Resource owner password credentials flow - * - **application**: Client credentials flow - * - **accessCode**: Authorization code flow - * - * @example "accessCode" - * @example "implicit" - * @example "password" - */ - flow?: "implicit" | "password" | "application" | "accessCode" - - /** - * The authorization URL to be used for this flow. This SHOULD be in the form of - * a URL. This field is required for oauth2 type and applies to oauth2 type only. - * - * @example "https://example.com/oauth/authorize" - * @example "https://api.example.com/oauth/authorize" - */ - authorizationUrl?: string - - /** - * The token URL to be used for this flow. This SHOULD be in the form of a URL. - * This field is required for oauth2 type and applies to oauth2 type only. - * - * @example "https://example.com/oauth/token" - * @example "https://api.example.com/oauth/token" - */ - tokenUrl?: string - - /** - * The available scopes for the OAuth2 security scheme. The key is the scope name - * and the value is a short description of the scope. This field is required for - * oauth2 type and applies to oauth2 type only. - * - * @example { "read": "Read access to resources", "write": "Write access to resources" } - * @example { "admin": "Administrative access" } - */ - scopes?: Scopes -} - -/** - * Scopes Object - * - * Lists the available scopes for an OAuth2 security scheme. - * - * @see https://swagger.io/specification/v2/#scopes-object - * @example - * ```typescript - * const scopes: Scopes = { - * "write:pets": "modify pets in your account", - * "read:pets": "read your pets" - * } - * ``` - */ -export interface Scopes { - /** - * Maps between a name of a scope to a short description of it (as the value of the property). - * The key is the scope name and the value is a short description of the scope. - * - * @example { "read": "Read access to resources", "write": "Write access to resources" } - * @example { "admin": "Administrative access" } - */ - [scopeName: string]: string -} - -/** - * Security Requirement Object - * - * Lists the required security schemes to execute this operation. The object can have - * multiple security schemes declared in it which are all required (that is, there is - * a logical AND between the schemes). The name used for each property MUST correspond - * to a security scheme declared in the Security Definitions. - * - * @see https://swagger.io/specification/v2/#security-requirement-object - * @example - * ```typescript - * // Non-OAuth2 Security Requirement - * const nonOAuth2Security: SecurityRequirement = { - * "api_key": [] - * } - * - * // OAuth2 Security Requirement - * const oauth2Security: SecurityRequirement = { - * "petstore_auth": [ - * "write:pets", - * "read:pets" - * ] - * } - * ``` - */ -export interface SecurityRequirement { - /** - * Each name must correspond to a security scheme which is declared in the Security Definitions. - * If the security scheme is of type "oauth2", then the value is a list of scope names - * required for the execution. For other security scheme types, the array MUST be empty. - * - * @example { "api_key": [] } - * @example { "oauth2": ["read", "write"] } - */ - [schemeName: string]: string[] -} - -/** - * Security Definitions Object - * - * A declaration of the security schemes available to be used in the specification. - * This does not enforce the security schemes on the operations and only serves to - * provide the relevant details for each scheme. - * - * @see https://swagger.io/specification/v2/#security-definitions-object - * @example - * ```typescript - * const securityDefinitions: SecurityDefinitions = { - * "api_key": { - * "type": "apiKey", - * "name": "api_key", - * "in": "header" - * }, - * "petstore_auth": { - * "type": "oauth2", - * "authorizationUrl": "http://swagger.io/api/oauth/dialog", - * "flow": "implicit", - * "scopes": { - * "write:pets": "modify pets in your account", - * "read:pets": "read your pets" - * } - * } - * } - * ``` - */ -export type SecurityDefinitions = Record diff --git a/2.0.0/spec.ts b/2.0.0/spec.ts deleted file mode 100644 index 277f25a..0000000 --- a/2.0.0/spec.ts +++ /dev/null @@ -1,225 +0,0 @@ -import type { Extension } from "./extensions" - -// Import all the major component types -import type { Info } from "./info" -import type { - PathItemObject, - Operation, - Parameter, - Response, - Header, - Items -} from "./paths" -import type { - Schema, - SwaggerSchema, - XML, - Definitions, - ParametersDefinitions, - ResponsesDefinitions -} from "./schema" -import type { - SecurityScheme, - SecurityRequirement, - Scopes, - SecurityDefinitions -} from "./security" -import type { Tag } from "./tags" -import type { ExternalDocumentation } from "./external-documentation" -import type { Reference } from "./references" -import type { Example } from "./example" -import type { Paths } from "./paths" - -/** - * Root Swagger 2.0 Schema (Swagger Object) - * - * This is the root document object of the OpenAPI specification. It contains - * all the metadata about the API being described. This object is based on the - * JSON Schema Specification Draft 4 and uses a predefined subset of it. - * - * The Swagger Object is the root of the specification document and contains - * all the information about the API, including its metadata, available paths, - * data models, security schemes, and more. - * - * @see https://swagger.io/specification/v2/#swagger-object - * @example - * ```typescript - * const swagger: Specification = { - * swagger: "2.0", - * info: { - * title: "Swagger Sample App", - * description: "This is a sample server Petstore server.", - * version: "1.0.1" - * }, - * host: "petstore.swagger.io", - * basePath: "/v2", - * schemes: ["https"], - * paths: { - * "/pets": { - * get: { - * summary: "List all pets", - * responses: { - * "200": { - * description: "A list of pets", - * schema: { - * type: "array", - * items: { $ref: "#/definitions/Pet" } - * } - * } - * } - * } - * } - * }, - * definitions: { - * Pet: { - * type: "object", - * properties: { - * id: { type: "integer", format: "int64" }, - * name: { type: "string" }, - * tag: { type: "string" } - * } - * } - * } - * } - * ``` - */ -export type Specification = { - /** - * Specifies the Swagger specification version being used. - * Must be "2.0" for this specification. - */ - swagger: "2.0" - - /** - * Provides metadata about the API. The metadata can be used by the clients - * if needed, and can be presented in the Swagger-UI for convenience. - */ - info: Info - - /** - * The host (name or IP) serving the API. This MUST be the host only and does - * not include the scheme nor sub-paths. It MAY include a port. If the host - * is not included, the host serving the documentation is to be used - * (including the port). The host does not support path templating. - * - * @example "api.example.com" - * @example "api.example.com:8080" - */ - host?: string - - /** - * The base path on which the API is served, which is relative to the host. - * If it is not included, the API is served directly under the host. - * The value MUST start with a leading slash (/). The basePath does not - * support path templating. - * - * @example "/v1" - * @example "/api/v2" - */ - basePath?: string - - /** - * The transfer protocol of the API. Values MUST be from the list: - * "http", "https", "ws", "wss". If the schemes is not included, the default - * scheme to be used is the one used to access the specification. - * - * @example ["https", "http"] - * @example ["wss"] - */ - schemes?: Array<"http" | "https" | "ws" | "wss"> - - /** - * A list of MIME types the APIs can consume. This is global to all APIs - * but can be overridden on specific API calls. Value MUST be as described - * under Mime Types. - * - * @example ["application/json"] - * @example ["application/xml", "application/json"] - */ - consumes?: string[] - - /** - * A list of MIME types the APIs can produce. This is global to all APIs - * but can be overridden on specific API calls. Value MUST be as described - * under Mime Types. - * - * @example ["application/json"] - * @example ["application/xml", "application/json"] - */ - produces?: string[] - - /** - * The available paths and operations for the API. This is the root of the - * Path Item Object. It does not define a path or a basePath, they are defined - * in the Paths Object. A relative path to an individual endpoint. The field - * name MUST begin with a slash. The path is appended to the basePath in order - * to construct the full URL. Path templating is allowed. - * - * @example { "/users": { get: { ... } } } - * @example { "/users/{id}": { get: { ... } } } - */ - paths: Paths - - /** - * An object to hold data types produced and consumed by operations. - * These data types can be primitives, arrays or models. - * - * @example { "User": { type: "object", properties: { ... } } } - */ - definitions?: Definitions - - /** - * An object to hold parameters that can be used across operations. - * This property does not define global parameters for all operations. - * - * @example { "pageParam": { name: "page", in: "query", type: "integer" } } - */ - parameters?: ParametersDefinitions - - /** - * An object to hold responses that can be used across operations. - * This property does not define global responses for all operations. - * - * @example { "NotFound": { description: "Entity not found" } } - */ - responses?: ResponsesDefinitions - - /** - * Security scheme definitions that can be used by the operations. - * Supported schemes are basic authentication, an API key (either as a header - * or as a query parameter) and OAuth2's common flows (implicit, password, - * application and access code). - * - * @example { "api_key": { type: "apiKey", in: "header", name: "X-API-Key" } } - */ - securityDefinitions?: SecurityDefinitions - - /** - * A declaration of which security schemes are applied for the API as a whole. - * The list of values describes alternative security schemes that can be used - * (that is, there is a logical OR between the security requirements). - * Individual operations can override this definition. - * - * @example [{ "api_key": [] }] - * @example [{ "oauth2": ["read", "write"] }] - */ - security?: SecurityRequirement[] - - /** - * A list of tags used by the specification with additional metadata. - * The order of the tags can be used to reflect on their order by the - * parsing tools. Not all tags that are used by the Operation Object must - * be declared. The tags that are not declared may be organized randomly - * or based on the tools' logic. Each tag name in the list MUST be unique. - * - * @example [{ name: "users", description: "User management" }] - */ - tags?: Tag[] - - /** - * Additional external documentation. - * - * @example { description: "Find out more about our API", url: "https://example.com/docs" } - */ - externalDocs?: ExternalDocumentation -} & Extension diff --git a/2.0.0/xml.ts b/2.0.0/xml.ts deleted file mode 100644 index 35e7518..0000000 --- a/2.0.0/xml.ts +++ /dev/null @@ -1,142 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * XML Object - * ----- - * - * A metadata object that allows for more fine-tuned XML model definitions. - * When using arrays, XML element names are not inferred (for singular/plural forms) - * and the name property should be used to add that information. - * - * The XML Object provides additional metadata to describe the XML representation - * format of schema properties. It allows for precise control over how JSON - * schema definitions are translated to XML, including element naming, namespaces, - * attributes, and array wrapping. - * - * | Version | Reference | - * |---|-----| - * | 2.0 | {@link https://swagger.io/specification/v2/#xml-object | Swagger 2.0 XML Object} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Replaces the name of the element/attribute used for the described schema property. - * @key `namespace` - The URL of the namespace definition. Value SHOULD be in the form of a URL. - * @key `prefix` - The prefix to be used for the name. - * @key `attribute` - Declares whether the property definition translates to an attribute instead of an element. Default value is false. - * @key `wrapped` - MAY be used only for an array definition. Signifies whether the array is wrapped. Default value is false. - * - * @note - * All fields are optional. The `wrapped` property only takes effect when defined - * alongside `type` being `array` (outside the items). When `wrapped` is true, - * arrays are wrapped in a container element. - * - * ----- - * Examples - * ----- - * - * @example (basic XML element): - * ```ts - * const basicXml: XMLObject = { - * name: "animal" - * }; - * ``` - * - * @example (XML attribute): - * ```ts - * const attributeXml: XMLObject = { - * name: "id", - * attribute: true - * }; - * ``` - * - * @example (namespaced XML): - * ```ts - * const namespacedXml: XMLObject = { - * name: "name", - * namespace: "http://swagger.io/schema/sample", - * prefix: "sample" - * }; - * ``` - * - * @example (wrapped array): - * ```ts - * const wrappedArrayXml: XMLObject = { - * name: "animals", - * wrapped: true - * }; - * ``` - * - * @example (array items with custom name): - * ```ts - * const arrayItemsXml: XMLObject = { - * name: "animal" - * }; - * ``` - * - * @example (complete XML definition): - * ```ts - * const completeXml: XMLObject = { - * name: "person", - * namespace: "http://example.com/schema", - * prefix: "ex", - * attribute: false, - * wrapped: false - * }; - * ``` - */ -export interface XMLObject extends Extension { - /** - * Replaces the name of the element/attribute used for the described schema property. - * When defined within the Items Object, it will affect the name of the individual - * XML elements within the list. When defined alongside type being array (outside - * the items), it will affect the wrapping element and only if wrapped is true. - * - * @example "animal" - * @example "item" - * @example "person" - */ - name?: string - - /** - * The URL of the namespace definition. Value SHOULD be in the form of a URL. - * - * @example "http://example.com/schema/sample" - * @example "http://www.w3.org/2001/XMLSchema" - * @example "http://swagger.io/schema/sample" - */ - namespace?: string - - /** - * The prefix to be used for the name. - * - * @example "sample" - * @example "xs" - * @example "ex" - */ - prefix?: string - - /** - * Declares whether the property definition translates to an attribute instead of an element. - * Default value is false. - * - * @default false - * @example true - * @example false - */ - attribute?: boolean - - /** - * MAY be used only for an array definition. Signifies whether the array is wrapped - * (for example, ) or unwrapped (). - * Default value is false. The definition takes effect only when defined alongside - * type being array (outside the items). - * - * @default false - * @example true - * @example false - */ - wrapped?: boolean -} diff --git a/2.0.0/2.0.md b/2.0/2.0.md similarity index 100% rename from 2.0.0/2.0.md rename to 2.0/2.0.md diff --git a/2.0.0/data-types/array.ts b/2.0/data-types/array.ts similarity index 50% rename from 2.0.0/data-types/array.ts rename to 2.0/data-types/array.ts index 3c81bd9..9b6df1b 100644 --- a/2.0.0/data-types/array.ts +++ b/2.0/data-types/array.ts @@ -1,4 +1,5 @@ -import type { Extension } from "../extensions" +import type { Extension } from "../extensions"; +import type { Schema } from "../schema"; /** * ----- @@ -6,7 +7,7 @@ import type { Extension } from "../extensions" * ----- * * Schema for array data types in Swagger 2.0. - * + * * Array schemas represent ordered collections of items, where each item conforms * to a specified schema. They are based on JSON Schema Draft 4 with Swagger-specific * adjustments, providing comprehensive validation for array data structures. @@ -24,15 +25,15 @@ import type { Extension } from "../extensions" * Fields * ----- * - * @key `type` - Must be "array" for array schemas. - * @key `items` - Required. Describes the type of items in the array. - * @key `description` - A short description of the array schema. - * @key `title` - A short title for the array schema. - * @key `default` - Declares the default value for the array. - * @key `maxItems` - Maximum number of items in the array. - * @key `minItems` - Minimum number of items in the array. - * @key `uniqueItems` - Whether all items in the array must be unique. - * @key `example` - Example array value. + * @property `type` - Must be "array" for array schemas. + * @property `items` - Required. Describes the type of items in the array. + * @property `description` - A short description of the array schema. + * @property `title` - A short title for the array schema. + * @property `default` - Declares the default value for the array. + * @property `maxItems` - Maximum number of items in the array. + * @property `minItems` - Minimum number of items in the array. + * @property `uniqueItems` - Whether all items in the array must be unique. + * @property `example` - Example array value. * * @note * Array schemas inherit common properties from BaseSchemaProperties and add @@ -75,7 +76,7 @@ import type { Extension } from "../extensions" * ```ts * const scoresSchema: ArraySchema = { * type: "array", - * items: { + * items: { * type: "number", * minimum: 0, * maximum: 100 @@ -105,56 +106,56 @@ import type { Extension } from "../extensions" * ``` */ export interface ArraySchema extends Extension { - /** - * The type of the schema. Must be "array" for array schemas. - * - * This property is required and must be set to "array" to indicate - * that this schema represents an ordered collection of items. - * - * @example "array" - */ - type: "array" - - /** - * Required if type is "array". Describes the type of items in the array. - * - * The definition is the same as the one from JSON Schema, but references - * the Swagger Schema Object definition instead. This allows for complex - * nested structures and references to other schema definitions. - * - * @example { type: "string" } - * @example { $ref: "#/definitions/User" } - * @example { type: "object", properties: { name: { type: "string" } } } - */ - items: any // Forward declaration to avoid circular imports - - /** - * An array is valid against "maxItems" if its length is less than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 | JSON Schema Validation - maxItems} - * - * @example 10 - * @example 100 - */ - maxItems?: number - - /** - * An array is valid against "minItems" if its length is greater than or equal to this value. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 | JSON Schema Validation - minItems} - * - * @example 1 - * @example 2 - */ - minItems?: number - - /** - * An array is valid against "uniqueItems" if all its elements are unique. - * - * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 | JSON Schema Validation - uniqueItems} - * - * @example true - * @example false - */ - uniqueItems?: boolean + /** + * The type of the schema. Must be "array" for array schemas. + * + * This property is required and must be set to "array" to indicate + * that this schema represents an ordered collection of items. + * + * @example "array" + */ + type: "array"; + + /** + * Required if type is "array". Describes the type of items in the array. + * + * The definition is the same as the one from JSON Schema, but references + * the Swagger Schema Object definition instead. This allows for complex + * nested structures and references to other schema definitions. + * + * @example { type: "string" } + * @example { $ref: "#/definitions/User" } + * @example { type: "object", properties: { name: { type: "string" } } } + */ + items: Schema; // Forward declaration to avoid circular imports + + /** + * An array is valid against "maxItems" if its length is less than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 | JSON Schema Validation - maxItems} + * + * @example 10 + * @example 100 + */ + maxItems?: number; + + /** + * An array is valid against "minItems" if its length is greater than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 | JSON Schema Validation - minItems} + * + * @example 1 + * @example 2 + */ + minItems?: number; + + /** + * An array is valid against "uniqueItems" if all its elements are unique. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 | JSON Schema Validation - uniqueItems} + * + * @example true + * @example false + */ + uniqueItems?: boolean; } diff --git a/2.0/data-types/boolean.ts b/2.0/data-types/boolean.ts new file mode 100644 index 0000000..cea50b3 --- /dev/null +++ b/2.0/data-types/boolean.ts @@ -0,0 +1,172 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Boolean Schema + * ----- + * + * Schema for boolean data types in Swagger 2.0. + * + * Boolean schemas represent true/false values and are used for flags, switches, + * and other binary state indicators in APIs. They are simple but essential + * data types that provide clear semantic meaning for binary choices. + * + * Boolean schemas are commonly used for feature flags, status indicators, + * configuration options, and other binary state representations. They support + * default values and examples to help API consumers understand the expected + * behavior. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "boolean" for boolean schemas. + * @property `description` - A short description of the boolean schema. + * @property `title` - A short title for the boolean schema. + * @property `default` - Declares the default value for the boolean. + * @property `example` - Example boolean value. + * + * @note + * Boolean schemas inherit common properties from BaseSchemaProperties. + * No additional validation properties are needed for boolean values as they + * are inherently simple (true/false only). + * + * ----- + * Examples + * ----- + * + * @example (feature flag boolean): + * ```ts + * const featureFlagSchema: BooleanSchema = { + * type: "boolean", + * description: "Whether the new feature is enabled", + * default: false, + * example: true + * }; + * ``` + * + * @example (status boolean): + * ```ts + * const isActiveSchema: BooleanSchema = { + * type: "boolean", + * description: "Whether the user account is active", + * default: true, + * example: true + * }; + * ``` + * + * @example (configuration boolean): + * ```ts + * const notificationsEnabledSchema: BooleanSchema = { + * type: "boolean", + * description: "Whether email notifications are enabled", + * default: true, + * example: false + * }; + * ``` + * + * @example (permission boolean): + * ```ts + * const canEditSchema: BooleanSchema = { + * type: "boolean", + * description: "Whether the user can edit this resource", + * example: true + * }; + * ``` + */ +export interface BooleanSchema extends Extension { + /** + * The type of the schema. Must be "boolean" for boolean schemas. + * + * This property is required and must be set to "boolean" to indicate + * that this schema represents true/false values. + * + * @example "boolean" + */ + type: "boolean"; + + /** + * The extending format for the previously mentioned type. + * See Swagger 2.0 Data Type Formats for further details. + * + * Formats provide additional semantic information about the data type, + * enabling more precise validation and better tooling support. Swagger 2.0 + * defines several standard formats, but custom formats are also allowed. + * + * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} + * + * @example "int32" + * @example "date" + * @example "email" + * @example "uuid" + */ + format?: string; + + /** + * A short description of the schema. GFM syntax can be used for rich text representation. + * + * This description should provide clear information about what the schema + * represents and how it should be used. It's commonly displayed in API + * documentation and code generation tools. + * + * @example "A user object containing basic information" + * @example "Email address in RFC 5322 format" + */ + description?: string; + + /** + * A short title for the schema. + * + * The title provides a human-readable name for the schema, often used + * in documentation and UI displays. It should be concise but descriptive. + * + * @example "User" + * @example "Pet" + * @example "Order" + */ + title?: string; + + /** + * Declares the value of the schema that the server will use if none is provided. + * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. + * + * This is a Swagger 2.0 specific requirement that differs from JSON Schema. + * The default value must be valid according to the schema's type and constraints. + * + * @example "defaultValue" + * @example 10 + * @example { name: "John", age: 30 } + * @example ["item1", "item2"] + */ + default?: unknown; + + /** + * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} + * + * @example ["option1", "option2", "option3"] + * @example ["red", "green", "blue"] + * @example [1, 2, 3, 4, 5] + */ + enum?: unknown[]; + + /** + * A free-form property to include an example of an instance for this schema. + * + * Examples help developers understand how to use the schema and what kind + * of data is expected. They are commonly used by documentation generators + * and API testing tools. + * + * @example { name: "Puma", id: 1 } + * @example "example string value" + * @example 42 + * @example ["item1", "item2"] + */ + example?: unknown; +} diff --git a/2.0/data-types/file.ts b/2.0/data-types/file.ts new file mode 100644 index 0000000..bbe25b3 --- /dev/null +++ b/2.0/data-types/file.ts @@ -0,0 +1,171 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * File Schema + * ----- + * + * Schema for file data types in Swagger 2.0. + * + * File schemas represent file uploads and downloads in APIs. This is a Swagger 2.0 + * specific data type that extends the JSON Schema specification to support file + * operations. File schemas are used by Parameter and Response objects to indicate + * that the data represents a file rather than a structured data type. + * + * File schemas are commonly used for file upload endpoints, document processing, + * image handling, and other file-based operations. They provide clear indication + * to API consumers that file data is expected or returned. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * | 2.0 | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} | + * | 2.0 | {@link https://swagger.io/specification/v2/#response-object | Swagger 2.0 Response Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "file" for file schemas. + * @property `description` - A short description of the file schema. + * @property `title` - A short title for the file schema. + * @property `example` - Example file information or description. + * + * @note + * File schemas are specific to Swagger 2.0 and are not part of the JSON Schema + * specification. They inherit common properties from BaseSchemaProperties. + * When used in parameters, the consumes property should specify appropriate + * MIME types like "multipart/form-data" or "application/x-www-form-urlencoded". + * + * ----- + * Examples + * ----- + * + * @example (file upload parameter): + * ```ts + * const fileUploadSchema: FileSchema = { + * type: "file", + * description: "Image file to upload", + * example: "user-avatar.jpg" + * }; + * ``` + * + * @example (document upload parameter): + * ```ts + * const documentSchema: FileSchema = { + * type: "file", + * description: "PDF document to process", + * example: "contract.pdf" + * }; + * ``` + * + * @example (file download response): + * ```ts + * const fileDownloadSchema: FileSchema = { + * type: "file", + * description: "Generated report file", + * example: "monthly-report.xlsx" + * }; + * ``` + * + * @example (image file parameter): + * ```ts + * const imageSchema: FileSchema = { + * type: "file", + * description: "Profile picture image", + * example: "profile-photo.png" + * }; + * ``` + */ +export interface FileSchema extends Extension { + /** + * The type of the schema. Must be "file" for file schemas. + * + * This property is required and must be set to "file" to indicate + * that this schema represents file data. This is a Swagger 2.0 specific + * type that extends JSON Schema. + * + * @example "file" + */ + type: "file"; + + /** + * The extending format for the previously mentioned type. + * See Swagger 2.0 Data Type Formats for further details. + * + * Formats provide additional semantic information about the data type, + * enabling more precise validation and better tooling support. Swagger 2.0 + * defines several standard formats, but custom formats are also allowed. + * + * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} + * + * @example "int32" + * @example "date" + * @example "email" + * @example "uuid" + */ + format?: string; + + /** + * A short description of the schema. GFM syntax can be used for rich text representation. + * + * This description should provide clear information about what the schema + * represents and how it should be used. It's commonly displayed in API + * documentation and code generation tools. + * + * @example "A user object containing basic information" + * @example "Email address in RFC 5322 format" + */ + description?: string; + + /** + * A short title for the schema. + * + * The title provides a human-readable name for the schema, often used + * in documentation and UI displays. It should be concise but descriptive. + * + * @example "User" + * @example "Pet" + * @example "Order" + */ + title?: string; + + /** + * Declares the value of the schema that the server will use if none is provided. + * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. + * + * This is a Swagger 2.0 specific requirement that differs from JSON Schema. + * The default value must be valid according to the schema's type and constraints. + * + * @example "defaultValue" + * @example 10 + * @example { name: "John", age: 30 } + * @example ["item1", "item2"] + */ + default?: unknown; + + /** + * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} + * + * @example ["option1", "option2", "option3"] + * @example ["red", "green", "blue"] + * @example [1, 2, 3, 4, 5] + */ + enum?: unknown[]; + + /** + * A free-form property to include an example of an instance for this schema. + * + * Examples help developers understand how to use the schema and what kind + * of data is expected. They are commonly used by documentation generators + * and API testing tools. + * + * @example { name: "Puma", id: 1 } + * @example "example string value" + * @example 42 + * @example ["item1", "item2"] + */ + example?: unknown; +} diff --git a/2.0/data-types/index.ts b/2.0/data-types/index.ts new file mode 100644 index 0000000..fcec18f --- /dev/null +++ b/2.0/data-types/index.ts @@ -0,0 +1,10 @@ +// Base schema properties + +export type { ArraySchema } from "./array"; +export type { BooleanSchema } from "./boolean"; +export type { FileSchema } from "./file"; +export type { IntegerSchema } from "./integer"; +export type { NumberSchema } from "./number"; +export type { ObjectSchema } from "./object"; +// Individual schema types +export type { StringSchema } from "./string"; diff --git a/2.0/data-types/integer.ts b/2.0/data-types/integer.ts new file mode 100644 index 0000000..7da9838 --- /dev/null +++ b/2.0/data-types/integer.ts @@ -0,0 +1,234 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Integer Schema + * ----- + * + * Schema for integer data types in Swagger 2.0. + * + * Integer schemas represent whole numbers without fractional components. + * They support various formats and validation rules to ensure data integrity + * and provide meaningful constraints for integer values. + * + * Integer schemas are commonly used for counts, IDs, timestamps, and other + * discrete numeric values in APIs. They support range validation and multiple + * format specifications including int32 and int64. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "integer" for integer schemas. + * @property `format` - The extending format for the integer type (e.g., "int32", "int64"). + * @property `description` - A short description of the integer schema. + * @property `title` - A short title for the integer schema. + * @property `default` - Declares the default value for the integer. + * @property `multipleOf` - The integer must be a multiple of this value. + * @property `maximum` - Maximum value for the integer. + * @property `exclusiveMaximum` - Whether the maximum value is exclusive. + * @property `minimum` - Minimum value for the integer. + * @property `exclusiveMinimum` - Whether the minimum value is exclusive. + * @property `example` - Example integer value. + * + * @note + * Integer schemas inherit common properties from BaseSchemaProperties and add + * numeric-specific validation properties. The `format` property is important + * for distinguishing between different integer representations (int32 vs int64). + * + * ----- + * Examples + * ----- + * + * @example (user ID integer): + * ```ts + * const userIdSchema: IntegerSchema = { + * type: "integer", + * format: "int64", + * description: "Unique user identifier", + * minimum: 1, + * example: 12345 + * }; + * ``` + * + * @example (age integer): + * ```ts + * const ageSchema: IntegerSchema = { + * type: "integer", + * format: "int32", + * description: "Person's age in years", + * minimum: 0, + * maximum: 150, + * example: 25 + * }; + * ``` + * + * @example (quantity integer): + * ```ts + * const quantitySchema: IntegerSchema = { + * type: "integer", + * format: "int32", + * description: "Item quantity", + * minimum: 0, + * maximum: 1000, + * multipleOf: 1, + * example: 5 + * }; + * ``` + * + * @example (timestamp integer): + * ```ts + * const timestampSchema: IntegerSchema = { + * type: "integer", + * format: "int64", + * description: "Unix timestamp in seconds", + * minimum: 0, + * example: 1640995200 + * }; + * ``` + */ +export interface IntegerSchema extends Extension { + /** + * The type of the schema. Must be "integer" for integer schemas. + * + * This property is required and must be set to "integer" to indicate + * that this schema represents whole number data without fractional components. + * + * @example "integer" + */ + type: "integer"; + + /** + * The extending format for the previously mentioned type. + * See Swagger 2.0 Data Type Formats for further details. + * + * Formats provide additional semantic information about the data type, + * enabling more precise validation and better tooling support. Swagger 2.0 + * defines several standard formats, but custom formats are also allowed. + * + * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} + * + * @example "int32" + * @example "int64" + */ + format?: string; + + /** + * A short description of the schema. GFM syntax can be used for rich text representation. + * + * This description should provide clear information about what the schema + * represents and how it should be used. It's commonly displayed in API + * documentation and code generation tools. + * + * @example "A user object containing basic information" + * @example "Email address in RFC 5322 format" + */ + description?: string; + + /** + * A short title for the schema. + * + * The title provides a human-readable name for the schema, often used + * in documentation and UI displays. It should be concise but descriptive. + * + * @example "User" + * @example "Pet" + * @example "Order" + */ + title?: string; + + /** + * Declares the value of the schema that the server will use if none is provided. + * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. + * + * This is a Swagger 2.0 specific requirement that differs from JSON Schema. + * The default value must be valid according to the schema's type and constraints. + * + * @example "defaultValue" + * @example 10 + * @example { name: "John", age: 30 } + * @example ["item1", "item2"] + */ + default?: unknown; + + /** + * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} + * + * @example ["option1", "option2", "option3"] + * @example ["red", "green", "blue"] + * @example [1, 2, 3, 4, 5] + */ + enum?: unknown[]; + + /** + * A free-form property to include an example of an instance for this schema. + * + * Examples help developers understand how to use the schema and what kind + * of data is expected. They are commonly used by documentation generators + * and API testing tools. + * + * @example { name: "Puma", id: 1 } + * @example "example string value" + * @example 42 + * @example ["item1", "item2"] + */ + example?: unknown; + + /** + * A number is valid against "multipleOf" if the result of the division + * of the instance by this keyword's value is an integer. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 | JSON Schema Validation - multipleOf} + * + * @example 2 + * @example 1 + */ + multipleOf?: number; + + /** + * A number is valid against "maximum" if it is less than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - maximum} + * + * @example 100 + * @example 2147483647 + */ + maximum?: number; + + /** + * A number is valid against "exclusiveMaximum" if it is strictly less than this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - exclusiveMaximum} + * + * @example false + * @example true + */ + exclusiveMaximum?: boolean; + + /** + * A number is valid against "minimum" if it is greater than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - minimum} + * + * @example 0 + * @example 1 + */ + minimum?: number; + + /** + * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - exclusiveMinimum} + * + * @example false + * @example true + */ + exclusiveMinimum?: boolean; +} diff --git a/2.0/data-types/number.ts b/2.0/data-types/number.ts new file mode 100644 index 0000000..b1ce90e --- /dev/null +++ b/2.0/data-types/number.ts @@ -0,0 +1,239 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Number Schema + * ----- + * + * Schema for number data types in Swagger 2.0. + * + * Number schemas represent numeric data including both integers and floating-point + * numbers. They support various formats and validation rules to ensure data + * integrity and provide meaningful constraints for numeric values. + * + * Number schemas are commonly used for quantities, prices, measurements, and + * other numeric data in APIs. They support range validation, precision control, + * and multiple format specifications. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "number" for number schemas. + * @property `format` - The extending format for the number type (e.g., "float", "double"). + * @property `description` - A short description of the number schema. + * @property `title` - A short title for the number schema. + * @property `default` - Declares the default value for the number. + * @property `multipleOf` - The number must be a multiple of this value. + * @property `maximum` - Maximum value for the number. + * @property `exclusiveMaximum` - Whether the maximum value is exclusive. + * @property `minimum` - Minimum value for the number. + * @property `exclusiveMinimum` - Whether the minimum value is exclusive. + * @property `example` - Example number value. + * + * @note + * Number schemas inherit common properties from BaseSchemaProperties and add + * numeric-specific validation properties. The `format` property is important + * for distinguishing between different numeric representations (float vs double). + * + * ----- + * Examples + * ----- + * + * @example (price number): + * ```ts + * const priceSchema: NumberSchema = { + * type: "number", + * format: "double", + * description: "Price in USD", + * minimum: 0, + * maximum: 999999.99, + * multipleOf: 0.01, + * example: 29.99 + * }; + * ``` + * + * @example (percentage number): + * ```ts + * const percentageSchema: NumberSchema = { + * type: "number", + * format: "float", + * description: "Percentage value", + * minimum: 0, + * maximum: 100, + * example: 85.5 + * }; + * ``` + * + * @example (coordinate number): + * ```ts + * const coordinateSchema: NumberSchema = { + * type: "number", + * format: "double", + * description: "Geographic coordinate", + * minimum: -180, + * maximum: 180, + * example: -122.4194 + * }; + * ``` + * + * @example (rating number): + * ```ts + * const ratingSchema: NumberSchema = { + * type: "number", + * format: "float", + * description: "User rating", + * minimum: 1, + * maximum: 5, + * multipleOf: 0.1, + * example: 4.5 + * }; + * ``` + */ +export interface NumberSchema extends Extension { + /** + * The type of the schema. Must be "number" for number schemas. + * + * This property is required and must be set to "number" to indicate + * that this schema represents numeric data (both integers and floating-point). + * + * @example "number" + */ + type: "number"; + + /** + * The extending format for the previously mentioned type. + * See Swagger 2.0 Data Type Formats for further details. + * + * Formats provide additional semantic information about the data type, + * enabling more precise validation and better tooling support. Swagger 2.0 + * defines several standard formats, but custom formats are also allowed. + * + * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} + * + * @example "int32" + * @example "date" + * @example "email" + * @example "uuid" + */ + format?: string; + + /** + * A short description of the schema. GFM syntax can be used for rich text representation. + * + * This description should provide clear information about what the schema + * represents and how it should be used. It's commonly displayed in API + * documentation and code generation tools. + * + * @example "A user object containing basic information" + * @example "Email address in RFC 5322 format" + */ + description?: string; + + /** + * A short title for the schema. + * + * The title provides a human-readable name for the schema, often used + * in documentation and UI displays. It should be concise but descriptive. + * + * @example "User" + * @example "Pet" + * @example "Order" + */ + title?: string; + + /** + * Declares the value of the schema that the server will use if none is provided. + * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. + * + * This is a Swagger 2.0 specific requirement that differs from JSON Schema. + * The default value must be valid according to the schema's type and constraints. + * + * @example "defaultValue" + * @example 10 + * @example { name: "John", age: 30 } + * @example ["item1", "item2"] + */ + default?: unknown; + + /** + * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} + * + * @example ["option1", "option2", "option3"] + * @example ["red", "green", "blue"] + * @example [1, 2, 3, 4, 5] + */ + enum?: unknown[]; + + /** + * A free-form property to include an example of an instance for this schema. + * + * Examples help developers understand how to use the schema and what kind + * of data is expected. They are commonly used by documentation generators + * and API testing tools. + * + * @example { name: "Puma", id: 1 } + * @example "example string value" + * @example 42 + * @example ["item1", "item2"] + */ + example?: unknown; + + /** + * A number is valid against "multipleOf" if the result of the division + * of the instance by this keyword's value is an integer. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 | JSON Schema Validation - multipleOf} + * + * @example 2 + * @example 0.01 + */ + multipleOf?: number; + + /** + * A number is valid against "maximum" if it is less than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - maximum} + * + * @example 100 + * @example 999.99 + */ + maximum?: number; + + /** + * A number is valid against "exclusiveMaximum" if it is strictly less than this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 | JSON Schema Validation - exclusiveMaximum} + * + * @example false + * @example true + */ + exclusiveMaximum?: boolean; + + /** + * A number is valid against "minimum" if it is greater than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - minimum} + * + * @example 0 + * @example 1 + */ + minimum?: number; + + /** + * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 | JSON Schema Validation - exclusiveMinimum} + * + * @example false + * @example true + */ + exclusiveMinimum?: boolean; +} diff --git a/2.0/data-types/object.ts b/2.0/data-types/object.ts new file mode 100644 index 0000000..50eb1fe --- /dev/null +++ b/2.0/data-types/object.ts @@ -0,0 +1,206 @@ +import type { Extension } from "../extensions"; +import type { Schema } from "../schema"; + +/** + * ----- + * Object Schema + * ----- + * + * Schema for object data types in Swagger 2.0. + * + * Object schemas represent structured data with named properties, where each + * property has its own schema definition. They are based on JSON Schema Draft 4 + * with Swagger-specific adjustments, providing comprehensive validation for + * complex data structures. + * + * Object schemas are commonly used for models, entities, and complex data + * structures in APIs. They support property definitions, required fields, + * additional properties, and composition through allOf. The properties + * reference Swagger Schema Objects instead of JSON Schema definitions. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "object" for object schemas. + * @property `properties` - The properties of the object. + * @property `required` - A list of required properties. + * @property `additionalProperties` - Additional properties for the object. + * @property `allOf` - An array of schemas that this schema must validate against. + * @property `description` - A short description of the object schema. + * @property `title` - A short title for the object schema. + * @property `default` - Declares the default value for the object. + * @property `maxProperties` - Maximum number of properties in the object. + * @property `minProperties` - Minimum number of properties in the object. + * @property `example` - Example object value. + * + * @note + * Object schemas inherit common properties from BaseSchemaProperties and add + * object-specific validation properties. The properties, additionalProperties, + * and allOf definitions reference the Swagger Schema Object instead of JSON Schema. + * + * ----- + * Examples + * ----- + * + * @example (simple object): + * ```ts + * const userSchema: ObjectSchema = { + * type: "object", + * properties: { + * id: { type: "integer", format: "int64" }, + * name: { type: "string" }, + * email: { type: "string", format: "email" } + * }, + * required: ["id", "name", "email"], + * example: { id: 1, name: "John Doe", email: "john@example.com" } + * }; + * ``` + * + * @example (object with additional properties): + * ```ts + * const configSchema: ObjectSchema = { + * type: "object", + * properties: { + * theme: { type: "string", enum: ["light", "dark"] }, + * language: { type: "string", default: "en" } + * }, + * additionalProperties: { type: "string" }, + * description: "User configuration with custom properties" + * }; + * ``` + * + * @example (object with composition): + * ```ts + * const extendedUserSchema: ObjectSchema = { + * type: "object", + * allOf: [ + * { $ref: "#/definitions/BaseUser" }, + * { + * type: "object", + * properties: { + * role: { type: "string", enum: ["admin", "user", "guest"] }, + * permissions: { type: "array", items: { type: "string" } } + * }, + * required: ["role"] + * } + * ], + * description: "Extended user with role and permissions" + * }; + * ``` + * + * @example (nested object): + * ```ts + * const addressSchema: ObjectSchema = { + * type: "object", + * properties: { + * street: { type: "string" }, + * city: { type: "string" }, + * state: { type: "string" }, + * zipCode: { type: "string", pattern: "^\\d{5}(-\\d{4})?$" }, + * country: { type: "string", default: "US" } + * }, + * required: ["street", "city", "state", "zipCode"], + * example: { + * street: "123 Main St", + * city: "Anytown", + * state: "CA", + * zipCode: "12345", + * country: "US" + * } + * }; + * ``` + */ +export interface ObjectSchema extends Extension { + /** + * The type of the schema. Must be "object" for object schemas. + * + * This property is required and must be set to "object" to indicate + * that this schema represents structured data with named properties. + * + * @example "object" + */ + type?: "object"; + + /** + * The properties of the object. The definition is the same as the one from + * JSON Schema, but references the Swagger Schema Object definition instead. + * + * Each property name maps to a schema definition that describes the type + * and validation rules for that property. Properties can be of any type + * supported by Swagger schemas, including primitives, objects, arrays, + * and references. + * + * @example { name: { type: "string" }, age: { type: "integer" } } + * @example { address: { $ref: "#/definitions/Address" } } + */ + properties?: Record; // Forward declaration to avoid circular imports + + /** + * A list of required properties. Properties marked as required being true + * MUST be present in the object. + * + * This array contains the names of properties that must be present in + * any valid instance of this object schema. Properties not listed here + * are considered optional. + * + * @example ["name", "email"] + * @example ["id", "type", "createdAt"] + */ + required?: string[]; + + /** + * Additional properties for the object. Can be a boolean or a schema. + * The definition is the same as the one from JSON Schema, but references + * the Swagger Schema Object definition instead. + * + * - If true, additional properties of any type are allowed + * - If false, no additional properties are allowed + * - If a schema, additional properties must conform to that schema + * + * @example true + * @example false + * @example { type: "string" } + * @example { $ref: "#/definitions/AdditionalProperty" } + */ + additionalProperties?: boolean | Schema; // Forward declaration to avoid circular imports + + /** + * An array of schemas that this schema must validate against. + * All schemas in the array must be valid for the object to be valid. + * The definition is the same as the one from JSON Schema, but references + * the Swagger Schema Object definition instead. + * + * This enables schema composition and inheritance patterns, allowing + * objects to extend or combine multiple base schemas. + * + * @example [{ $ref: "#/definitions/BaseUser" }, { type: "object", properties: { ... } }] + * @example [{ $ref: "#/definitions/Identifiable" }, { $ref: "#/definitions/Timestamped" }] + */ + allOf?: Schema[]; // Forward declaration to avoid circular imports + + /** + * An object is valid against "maxProperties" if its number of properties is less than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.4.1 | JSON Schema Validation - maxProperties} + * + * @example 10 + * @example 50 + */ + maxProperties?: number; + + /** + * An object is valid against "minProperties" if its number of properties is greater than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.4.2 | JSON Schema Validation - minProperties} + * + * @example 1 + * @example 2 + */ + minProperties?: number; +} diff --git a/2.0/data-types/string.ts b/2.0/data-types/string.ts new file mode 100644 index 0000000..60f2e7a --- /dev/null +++ b/2.0/data-types/string.ts @@ -0,0 +1,225 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * String Schema + * ----- + * + * Schema for string data types in Swagger 2.0. + * + * String schemas represent textual data and support various formats and validation + * rules. They are one of the most commonly used schema types in API specifications, + * used for names, descriptions, identifiers, and other text-based data. + * + * String schemas support a wide range of formats including standard formats like + * email, date, and UUID, as well as custom formats defined by the API provider. + * They also support comprehensive validation through pattern matching, length + * constraints, and enumeration. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "string" for string schemas. + * @property `format` - The extending format for the string type. See Data Type Formats for further details. + * @property `description` - A short description of the string schema. + * @property `title` - A short title for the string schema. + * @property `default` - Declares the default value for the string. + * @property `maxLength` - Maximum length of the string. + * @property `minLength` - Minimum length of the string. + * @property `pattern` - Regular expression pattern the string must match. + * @property `enum` - Array of allowed string values. + * @property `example` - Example string value. + * + * @note + * String schemas include only properties that are valid for string types. + * This ensures type safety and prevents invalid property combinations. + * + * ----- + * Examples + * ----- + * + * @example (email string): + * ```ts + * const emailSchema: StringSchema = { + * type: "string", + * format: "email", + * description: "User email address", + * pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", + * maxLength: 254, + * minLength: 5, + * example: "user@example.com" + * }; + * ``` + * + * @example (date string): + * ```ts + * const dateSchema: StringSchema = { + * type: "string", + * format: "date", + * description: "Date in YYYY-MM-DD format", + * pattern: "^\\d{4}-\\d{2}-\\d{2}$", + * example: "2023-12-25" + * }; + * ``` + * + * @example (enum string): + * ```ts + * const statusSchema: StringSchema = { + * type: "string", + * description: "Order status", + * enum: ["pending", "processing", "shipped", "delivered", "cancelled"], + * default: "pending", + * example: "pending" + * }; + * ``` + * + * @example (custom format string): + * ```ts + * const uuidSchema: StringSchema = { + * type: "string", + * format: "uuid", + * description: "Universally unique identifier", + * pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", + * example: "550e8400-e29b-41d4-a716-446655440000" + * }; + * ``` + */ +export interface StringSchema extends Extension { + /** + * The type of the schema. Must be "string" for string schemas. + * + * This property is required and must be set to "string" to indicate + * that this schema represents string data. + * + * @see {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Specification - type} + * + * @example "string" + */ + type: "string"; + + /** + * The extending format for the previously mentioned type. + * See Swagger 2.0 Data Type Formats for further details. + * + * Formats provide additional semantic information about the data type, + * enabling more precise validation and better tooling support. Swagger 2.0 + * defines several standard formats, but custom formats are also allowed. + * + * @see {@link https://swagger.io/specification/v2/#dataTypeFormat | Swagger 2.0 Data Type Formats} + * + * @example "int32" + * @example "date" + * @example "email" + * @example "uuid" + */ + format?: string; + + /** + * A short description of the schema. GFM syntax can be used for rich text representation. + * + * This description should provide clear information about what the schema + * represents and how it should be used. It's commonly displayed in API + * documentation and code generation tools. + * + * @see {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Specification - description} + * + * @example "A user object containing basic information" + * @example "Email address in RFC 5322 format" + */ + description?: string; + + /** + * A short title for the schema. + * + * The title provides a human-readable name for the schema, often used + * in documentation and UI displays. It should be concise but descriptive. + * + * @see {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Specification - title} + * + * @example "User" + * @example "Pet" + * @example "Order" + */ + title?: string; + + /** + * Declares the value of the schema that the server will use if none is provided. + * Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. + * + * This is a Swagger 2.0 specific requirement that differs from JSON Schema. + * The default value must be valid according to the schema's type and constraints. + * + * @see {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Specification - default} + * + * @example "defaultValue" + * @example 10 + * @example { name: "John", age: 30 } + * @example ["item1", "item2"] + */ + default?: unknown; + + /** + * An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 | JSON Schema Validation - enum} + * + * @example ["option1", "option2", "option3"] + * @example ["red", "green", "blue"] + * @example [1, 2, 3, 4, 5] + */ + enum?: unknown[]; + + /** + * A free-form property to include an example of an instance for this schema. + * + * Examples help developers understand how to use the schema and what kind + * of data is expected. They are commonly used by documentation generators + * and API testing tools. + * + * @see {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Specification - example} + * + * @example { name: "Puma", id: 1 } + * @example "example string value" + * @example 42 + * @example ["item1", "item2"] + */ + example?: unknown; + + /** + * A string is valid against "maxLength" if its length is less than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 | JSON Schema Validation - maxLength} + * + * @example 100 + * @example 255 + */ + maxLength?: number; + + /** + * A string is valid against "minLength" if its length is greater than or equal to this value. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 | JSON Schema Validation - minLength} + * + * @example 1 + * @example 8 + */ + minLength?: number; + + /** + * A string is valid against "pattern" if the regular expression matches the string successfully. + * The regular expression syntax follows ECMA 262. + * + * @see {@link https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 | JSON Schema Validation - pattern} + * @see {@link https://www.ecma-international.org/ecma-262/5.1/#sec-15.10 | ECMA 262 Regular Expression Syntax} + * + * @example "^[a-zA-Z0-9]+$" + * @example "^\\d{4}-\\d{2}-\\d{2}$" + */ + pattern?: string; +} diff --git a/2.0.0/example.ts b/2.0/example.ts similarity index 63% rename from 2.0.0/example.ts rename to 2.0/example.ts index 8220232..ae3aaa4 100644 --- a/2.0.0/example.ts +++ b/2.0/example.ts @@ -1,4 +1,4 @@ -import type { Extension } from "./extensions" +import type { Extension } from "./extensions"; /** * ----- @@ -21,7 +21,7 @@ import type { Extension } from "./extensions" * Fields * ----- * - * @key `[mimeType]` - The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. + * @property `[mimeType]` - The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. * * @note * The property names correspond to MIME types that the operation can produce. @@ -59,17 +59,17 @@ import type { Extension } from "./extensions" * ``` */ export interface Example extends Extension { - /** - * The name of the property MUST be one of the Operation produces values - * (either implicit or inherited). The value SHOULD be an example of what - * such a response would look like. - * - * The property name corresponds to a MIME type that the operation can produce. - * The value should be a realistic example of the response data in that format. - * - * @example { "application/json": { name: "Puma", type: "Dog" } } - * @example { "application/xml": "Puma" } - * @example { "text/plain": "Success" } - */ - [mimeType: string]: unknown + /** + * The name of the property MUST be one of the Operation produces values + * (either implicit or inherited). The value SHOULD be an example of what + * such a response would look like. + * + * The property name corresponds to a MIME type that the operation can produce. + * The value should be a realistic example of the response data in that format. + * + * @example { "application/json": { name: "Puma", type: "Dog" } } + * @example { "application/xml": "Puma" } + * @example { "text/plain": "Success" } + */ + [mimeType: string]: unknown; } diff --git a/2.0.0/extensions.ts b/2.0/extensions.ts similarity index 73% rename from 2.0.0/extensions.ts rename to 2.0/extensions.ts index 5a19b4c..ae95915 100644 --- a/2.0.0/extensions.ts +++ b/2.0/extensions.ts @@ -24,7 +24,7 @@ * Extension Rules * ----- * - * @key `x-${string}` - Vendor extensions allow adding custom properties to Swagger objects. + * @property `x-${string}` - Vendor extensions allow adding custom properties to Swagger objects. * * @note * - All extension property names MUST begin with "x-" followed by any valid identifier @@ -96,20 +96,20 @@ * ``` */ export type Extension = { - /** - * Vendor extensions allow adding custom properties to Swagger objects. - * All extension property names MUST begin with "x-" followed by any valid identifier. - * The value can be any valid JSON value (null, primitive, array, or object). - * - * Extensions enable API providers to add custom functionality and metadata - * to their specifications without breaking compatibility with standard - * Swagger tools. They should be used consistently and documented properly. - * - * @example { "x-internal-id": "12345" } - * @example { "x-custom-feature": { enabled: true, version: "1.0" } } - * @example { "x-tags": ["internal", "beta"] } - * @example { "x-deprecated": true } - * @example { "x-optional-field": null } - */ - [K in `x-${string}`]: unknown -} + /** + * Vendor extensions allow adding custom properties to Swagger objects. + * All extension property names MUST begin with "x-" followed by any valid identifier. + * The value can be any valid JSON value (null, primitive, array, or object). + * + * Extensions enable API providers to add custom functionality and metadata + * to their specifications without breaking compatibility with standard + * Swagger tools. They should be used consistently and documented properly. + * + * @example { "x-internal-id": "12345" } + * @example { "x-custom-feature": { enabled: true, version: "1.0" } } + * @example { "x-tags": ["internal", "beta"] } + * @example { "x-deprecated": true } + * @example { "x-optional-field": null } + */ + [K in `x-${string}`]: unknown; +}; diff --git a/2.0.0/externalDocs.ts b/2.0/externalDocs.ts similarity index 59% rename from 2.0.0/externalDocs.ts rename to 2.0/externalDocs.ts index 428c965..e1a4417 100644 --- a/2.0.0/externalDocs.ts +++ b/2.0/externalDocs.ts @@ -1,4 +1,4 @@ -import type { Extension } from "./extensions" +import type { Extension } from "./extensions"; /** * ----- @@ -25,8 +25,8 @@ import type { Extension } from "./extensions" * Fields * ----- * - * @key `description` - A short description of the target documentation. GFM syntax can be used for rich text representation. - * @key `url` - The URL for the target documentation. Value MUST be in the format of a URL. This field is required. + * @property `description` - A short description of the target documentation. GFM syntax can be used for rich text representation. + * @property `url` - The URL for the target documentation. Value MUST be in the format of a URL. This field is required. * * @note * The `url` field is required and must be a valid URL. The `description` field @@ -84,32 +84,36 @@ import type { Extension } from "./extensions" * ``` */ export interface ExternalDocumentation extends Extension { - /** - * A short description of the target documentation. GFM syntax can be used for - * rich text representation. - * - * This description provides context about what the external documentation - * contains and helps developers understand when and why they should - * reference it. - * - * @example "Find more info here" - * @example "Complete API documentation with examples and tutorials" - * @example "SDK documentation and code examples" - * @example "Step-by-step integration guide" - */ - description?: string - - /** - * The URL for the target documentation. Value MUST be in the format of a URL. - * This field is required. - * - * The URL should point to a valid, accessible resource that provides - * additional documentation about the API or specific aspects of it. - * - * @example "https://swagger.io" - * @example "https://docs.example.com/api" - * @example "https://github.com/example/sdk" - * @example "https://example.com/integration-guide" - */ - url: string + /** + * A short description of the target documentation. GFM syntax can be used for + * rich text representation. + * + * This description provides context about what the external documentation + * contains and helps developers understand when and why they should + * reference it. + * + * @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - description} + * + * @example "Find more info here" + * @example "Complete API documentation with examples and tutorials" + * @example "SDK documentation and code examples" + * @example "Step-by-step integration guide" + */ + description?: string; + + /** + * The URL for the target documentation. Value MUST be in the format of a URL. + * This field is required. + * + * The URL should point to a valid, accessible resource that provides + * additional documentation about the API or specific aspects of it. + * + * @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - url} + * + * @example "https://swagger.io" + * @example "https://docs.example.com/api" + * @example "https://github.com/example/sdk" + * @example "https://example.com/integration-guide" + */ + url: string; } diff --git a/2.0/index.ts b/2.0/index.ts new file mode 100644 index 0000000..28dd986 --- /dev/null +++ b/2.0/index.ts @@ -0,0 +1,77 @@ +// Centralized exports for OpenAPI 2.0 types +// This file serves as the main entry point for all OpenAPI 2.0 type definitions + +export type { + ArraySchema, + BooleanSchema, + FileSchema, + IntegerSchema, + NumberSchema, + ObjectSchema, + // Individual schema types + StringSchema, +} from "./data-types"; +export type { Example } from "./example"; +// Re-export all types for convenience +export type { + // Core types + Extension, +} from "./extensions"; +export type { ExternalDocumentation } from "./externalDocs"; +export type { + Contact, + // Info types + Info, + License, +} from "./info"; +export type { + Header, + Items, + Operation, + Parameter, + // Path types + PathItemObject, + Paths, + Response, +} from "./paths"; +export type { + // References + BaseReference, + Reference, +} from "./references"; +export type { + Definitions, + ParametersDefinitions, + ResponsesDefinitions, + // Schema types + Schema, + XML, +} from "./schema"; +export type { + Scopes, + SecurityDefinitions, + SecurityRequirement, + // Security types + SecurityScheme, +} from "./security"; +// Export the main specification type +export type { Specification } from "./spec"; +export type { + // Utility types + Tag, +} from "./tags"; +export type { + // XML Object + XMLObject, +} from "./xml"; + +// All supporting types are now defined in their respective modules: +// - spec.ts: Specification (main root type) +// - info.ts: Info, Contact, License +// - paths.ts: PathItemObject, Operation, Parameter, Response, Header, Items +// - schema.ts: Schema, XML, Definitions, ParametersDefinitions, ResponsesDefinitions +// - security.ts: SecurityScheme, SecurityRequirement, Scopes, SecurityDefinitions +// - shallow.ts: Tag, ExternalDocumentation, Reference, Example, Paths +// - data-types/: All individual schema types +// - xml-object.ts: XMLObject +// - references.ts: BaseReference, Reference diff --git a/2.0/info.ts b/2.0/info.ts new file mode 100644 index 0000000..0989cb8 --- /dev/null +++ b/2.0/info.ts @@ -0,0 +1,226 @@ +import type { Extension } from "./extensions"; + +/** + * Info Object + * + * The object provides metadata about the API. The metadata can be used by the clients + * if needed, and can be presented in the Swagger-UI for convenience. + * + * @see https://swagger.io/specification/v2/#info-object + * @example + * ```typescript + * const info: Info = { + * title: "Swagger Sample App", + * description: "This is a sample server Petstore server.", + * termsOfService: "http://swagger.io/terms/", + * contact: { + * name: "API Support", + * url: "http://www.swagger.io/support", + * email: "support@swagger.io" + * }, + * license: { + * name: "Apache 2.0", + * url: "http://www.apache.org/licenses/LICENSE-2.0.html" + * }, + * version: "1.0.1" + * } + * ``` + */ +export interface Info extends Extension { + /** + * The title of the application. This field is required. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - title} + * + * @example "Swagger Sample App" + * @example "My API" + */ + title: string; + + /** + * A short description of the application. GFM syntax can be used for rich text representation. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - description} + * + * @example "This is a sample server Petstore server." + * @example "A comprehensive API for managing user data" + */ + description?: string; + + /** + * The Terms of Service for the API. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - termsOfService} + * + * @example "http://swagger.io/terms/" + * @example "https://example.com/terms" + */ + termsOfService?: string; + + /** + * The contact information for the exposed API. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - contact} + * + * @example { name: "API Support", email: "support@example.com" } + */ + contact?: Contact; + + /** + * The license information for the exposed API. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - license} + * + * @example { name: "Apache 2.0", url: "http://www.apache.org/licenses/LICENSE-2.0.html" } + */ + license?: License; + + /** + * Provides the version of the application API (not to be confused with the specification version). + * This field is required. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - version} + * + * @example "1.0.1" + * @example "2.0.0" + */ + version: string; +} + +/** + * Contact Object + * + * Contact information for the exposed API. + * + * @see https://swagger.io/specification/v2/#contact-object + * @example + * ```typescript + * const contact: Contact = { + * name: "API Support", + * url: "http://www.swagger.io/support", + * email: "support@swagger.io" + * } + * ``` + */ +export interface Contact extends Extension { + /** + * The identifying name of the contact person/organization. + * + * @see {@link https://swagger.io/specification/v2/#contact-object | Swagger 2.0 Specification - name} + * + * @example "API Support" + * @example "John Doe" + */ + name?: string; + + /** + * The URL pointing to the contact information. MUST be in the format of a URL. + * + * @see {@link https://swagger.io/specification/v2/#contact-object | Swagger 2.0 Specification - url} + * + * @example "http://www.swagger.io/support" + * @example "https://example.com/contact" + */ + url?: string; + + /** + * The email address of the contact person/organization. MUST be in the format of an email address. + * + * @see {@link https://swagger.io/specification/v2/#contact-object | Swagger 2.0 Specification - email} + * + * @example "support@swagger.io" + * @example "contact@example.com" + */ + email?: string; +} + +/** + * ----- + * License Object + * ----- + * + * License information for the exposed API. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#license-object | Swagger 2.0 License} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The license name used for the API + * @property `url` - Optional A URL to the license used for the API + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` field is required. The `url` field is optional but recommended. + * + * ----- + * Examples + * ----- + * + * @example (MIT License): + * ```ts + * const license: License = { + * name: "MIT License", + * url: "https://opensource.org/license/mit/" + * }; + * ``` + * + * @example (Apache 2.0): + * ```ts + * const license: License = { + * name: "Apache License 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0" + * }; + * ``` + * + * @example (custom license): + * ```ts + * const license: License = { + * name: "Proprietary Foo License", + * url: "https://example.com/licenses/foo-1.0" + * }; + * ``` + * + * @example (license without URL): + * ```ts + * const license: License = { + * name: "Custom License" + * }; + * ``` + * + * @example (license with extensions): + * ```ts + * const license: License = { + * name: "MIT License", + * url: "https://opensource.org/license/mit/", + * "x-custom": "value", + * "x-internal": true + * }; + * ``` + */ +export interface License extends Extension { + /** + * The license name used for the API. This field is required. + * + * @see {@link https://swagger.io/specification/v2/#license-object | Swagger 2.0 Specification - name} + * + * @example "MIT License" + * @example "Apache License 2.0" + * @example "Proprietary Foo License" + */ + name: string; + + /** + * A URL to the license used for the API. MUST be in the format of a URL. + * + * @see {@link https://swagger.io/specification/v2/#license-object | Swagger 2.0 Specification - url} + * + * @example "https://opensource.org/license/mit/" + * @example "https://www.apache.org/licenses/LICENSE-2.0" + * @example "https://example.com/licenses/foo-1.0" + */ + url?: string; +} diff --git a/2.0/paths.ts b/2.0/paths.ts new file mode 100644 index 0000000..f476859 --- /dev/null +++ b/2.0/paths.ts @@ -0,0 +1,1220 @@ +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +import type { BaseReference } from "./references"; +import type { Schema } from "./schema"; +import type { ResponsesMap } from "./status"; + +/** + * Path Item Object + * + * Describes the operations available on a single path. A Path Item may be empty, + * due to ACL constraints. The path itself is still exposed to the documentation + * viewer but they will not know which operations and parameters are available. + * + * @see https://swagger.io/specification/v2/#path-item-object + * @example + * ```typescript + * const pathItem: PathItemObject = { + * get: { + * summary: "Get users", + * operationId: "getUsers", + * responses: { + * "200": { + * description: "List of users", + * schema: { type: "array", items: { $ref: "#/definitions/User" } } + * } + * } + * }, + * post: { + * summary: "Create user", + * operationId: "createUser", + * parameters: [ + * { + * name: "user", + * in: "body", + * schema: { $ref: "#/definitions/User" } + * } + * ], + * responses: { + * "201": { + * description: "User created", + * schema: { $ref: "#/definitions/User" } + * } + * } + * }, + * parameters: [ + * { + * name: "limit", + * in: "query", + * type: "integer", + * description: "Maximum number of items to return" + * } + * ] + * } + * ``` + */ +export type PathItemObject = + | ({ + /** + * A definition of a GET operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - get} + * + * @example { summary: "Get users", responses: { "200": { description: "Success" } } } + */ + get?: Operation; + + /** + * A definition of a PUT operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - put} + * + * @example { summary: "Update user", responses: { "200": { description: "Success" } } } + */ + put?: Operation; + + /** + * A definition of a POST operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - post} + * + * @example { summary: "Create user", responses: { "201": { description: "Created" } } } + */ + post?: Operation; + + /** + * A definition of a DELETE operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - delete} + * + * @example { summary: "Delete user", responses: { "204": { description: "No Content" } } } + */ + delete?: Operation; + + /** + * A definition of an OPTIONS operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - options} + * + * @example { summary: "Get options", responses: { "200": { description: "Options" } } } + */ + options?: Operation; + + /** + * A definition of a HEAD operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - head} + * + * @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } } + */ + head?: Operation; + + /** + * A definition of a PATCH operation on this path. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - patch} + * + * @example { summary: "Partially update user", responses: { "200": { description: "Success" } } } + */ + patch?: Operation; + + /** + * A list of parameters that are applicable for all the operations described + * under this path. These parameters can be overridden at the operation level, + * but cannot be removed there. The list MUST NOT include duplicated parameters. + * A unique parameter is defined by a combination of a name and location. + * + * @see {@link https://swagger.io/specification/v2/#path-item-object | Swagger 2.0 Specification - parameters} + * + * @example [{ name: "limit", in: "query", type: "integer" }] + */ + parameters?: Array; + } & Extension) + | BaseReference; + +/** + * Operation Object + * + * Describes a single API operation on a path. A unique operation is defined + * by a combination of a path and an HTTP method. + * + * @see https://swagger.io/specification/v2/#operation-object + * @example + * ```typescript + * const operation: Operation = { + * tags: ["users"], + * summary: "Get user by ID", + * description: "Retrieves a specific user by their unique identifier", + * operationId: "getUserById", + * consumes: ["application/json"], + * produces: ["application/json"], + * parameters: [ + * { + * name: "id", + * in: "path", + * required: true, + * type: "string", + * description: "The user ID" + * } + * ], + * responses: { + * "200": { + * description: "User found", + * schema: { $ref: "#/definitions/User" } + * }, + * "404": { + * description: "User not found" + * } + * }, + * deprecated: false, + * security: [{ "api_key": [] }] + * } + * ``` + */ +export interface Operation extends Extension { + /** + * A list of tags for API documentation control. Tags can be used for logical + * grouping of operations by resources or any other qualifier. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - tags} + * + * @example ["users", "authentication"] + * @example ["pets"] + */ + tags?: string[]; + + /** + * A short summary of what the operation does. For maximum readability in + * swagger-ui, this field SHOULD be less than 120 characters. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - summary} + * + * @example "Get user by ID" + * @example "Create a new pet" + */ + summary?: string; + + /** + * A verbose explanation of the operation behavior. GFM syntax can be used + * for rich text representation. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - description} + * + * @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information." + */ + description?: string; + + /** + * Additional external documentation for this operation. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - externalDocs} + * + * @example { description: "Find out more about this operation", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Unique string used to identify the operation. The id MUST be unique among + * all operations described in the API. Tools and libraries MAY use the + * operationId to uniquely identify an operation, therefore, it is recommended + * to follow common programming naming conventions. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - operationId} + * + * @example "getUserById" + * @example "createPet" + */ + operationId?: string; + + /** + * A list of MIME types the operation can consume. This overrides the consumes + * definition at the Swagger Object level. An empty value MAY be used to clear + * the global definition. Value MUST be as described under Mime Types. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - consumes} + * + * @example ["application/json"] + * @example ["application/xml", "application/json"] + */ + consumes?: string[]; + + /** + * A list of MIME types the operation can produce. This overrides the produces + * definition at the Swagger Object level. An empty value MAY be used to clear + * the global definition. Value MUST be as described under Mime Types. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - produces} + * + * @example ["application/json"] + * @example ["application/xml", "application/json"] + */ + produces?: string[]; + + /** + * A list of parameters that are applicable for this operation. If a parameter + * is already defined at the Path Item, the new definition will override it + * but can never remove it. The list MUST NOT include duplicated parameters. + * A unique parameter is defined by a combination of a name and location. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - parameters} + * + * @example [{ name: "id", in: "path", required: true, type: "string" }] + */ + parameters?: Array; + + /** + * The list of possible responses as they are returned from executing this operation. + * This field MUST be present and MUST contain at least one response. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - responses} + * + * @example { "200": { description: "Success", schema: { type: "object" } } } + */ + responses: ResponsesMap; + + /** + * The transfer protocol for the operation. Values MUST be from the list: + * "http", "https", "ws", "wss". The value overrides the Swagger Object + * schemes definition. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - schemes} + * + * @example ["https", "http"] + * @example ["wss"] + */ + schemes?: Array<"http" | "https" | "ws" | "wss">; + + /** + * Declares this operation to be deprecated. Usage of the declared operation + * should be refrained. Default value is false. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - deprecated} + * + * @default false + * @example true + */ + deprecated?: boolean; + + /** + * A declaration of which security schemes are applied for this operation. + * The list of values describes alternative security schemes that can be used + * (that is, there is a logical OR between the security requirements). + * This definition overrides any declared top-level security. To remove a + * top-level security declaration, an empty array can be used. + * + * @see {@link https://swagger.io/specification/v2/#operation-object | Swagger 2.0 Specification - security} + * + * @example [{ "api_key": [] }] + * @example [{ "oauth2": ["read", "write"] }] + */ + security?: Array>; +} + +/** + * Parameter Object + * + * Describes a single operation parameter. A unique parameter is defined by a + * combination of a name and location. + * + * @see https://swagger.io/specification/v2/#parameter-object + * @example + * ```typescript + * // Query parameter + * const queryParam: Parameter = { + * name: "limit", + * in: "query", + * description: "Maximum number of items to return", + * required: false, + * type: "integer", + * format: "int32" + * } + * + * // Path parameter + * const pathParam: Parameter = { + * name: "id", + * in: "path", + * description: "The user ID", + * required: true, + * type: "string" + * } + * + * // Body parameter + * const bodyParam: Parameter = { + * name: "user", + * in: "body", + * description: "User object to create", + * required: true, + * schema: { $ref: "#/definitions/User" } + * } + * ``` + */ +/** + * ----- + * Parameter Object (Body Parameter) + * ----- + * + * Describes a body parameter for an API operation. Body parameters represent + * the payload that's appended to the HTTP request. Since there can only be one + * payload, there can only be one body parameter per operation. + * + * Body parameters use a schema to define the structure of the request payload, + * which can be any valid Swagger schema including objects, arrays, and primitives. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - The name of the parameter (used for documentation purposes only) + * @property `in` - Must be "body" for body parameters + * @property `description` - A brief description of the parameter + * @property `required` - Whether the parameter is mandatory + * @property `schema` - The schema defining the type used for the body parameter (required) + * @property `x-${string}` - Specification Extensions + * + * @note + * Body parameters are mutually exclusive with form parameters for the same operation. + * The schema property is required for body parameters. + * + * ----- + * Examples + * ----- + * + * @example (body parameter with schema reference): + * ```ts + * const bodyParam: BodyParameter = { + * name: "user", + * in: "body", + * description: "User object to create", + * required: true, + * schema: { $ref: "#/definitions/User" } + * }; + * ``` + * + * @example (body parameter with inline schema): + * ```ts + * const bodyParam: BodyParameter = { + * name: "data", + * in: "body", + * description: "Request data", + * required: true, + * schema: { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "integer" } + * } + * } + * }; + * ``` + */ +export interface BodyParameter extends Extension { + /** + * The name of the parameter. For body parameters, this is used for documentation + * purposes only and has no effect on the parameter itself. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - name} + * + * @example "user" + * @example "data" + * @example "payload" + */ + name: string; + + /** + * The location of the parameter. Must be "body" for body parameters. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - in} + * + * @example "body" + */ + in: "body"; + + /** + * A brief description of the parameter. This could contain examples of use. + * GFM syntax can be used for rich text representation. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - description} + * + * @example "User object to create" + * @example "Request payload containing the data to process" + */ + description?: string; + + /** + * Determines whether this parameter is mandatory. Default value is false. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - required} + * + * @default false + * @example true + */ + required?: boolean; + + /** + * The schema defining the type used for the body parameter. This property is + * required for body parameters. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - schema} + * + * @example { $ref: "#/definitions/User" } + * @example { type: "object", properties: { name: { type: "string" } } } + */ + schema: Schema; +} + +/** + * ----- + * Parameter Object (Non-Body Parameter) + * ----- + * + * Describes a non-body parameter for an API operation. These parameters include + * query, header, path, and formData parameters. They have different validation + * rules and properties compared to body parameters. + * + * Non-body parameters support simple types (string, number, integer, boolean, array, file) + * and include validation properties like format, pattern, minimum, maximum, etc. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Parameter Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - The name of the parameter + * @property `in` - The location of the parameter ("query", "header", "path", "formData") + * @property `description` - A brief description of the parameter + * @property `required` - Whether the parameter is mandatory (required for path parameters) + * @property `type` - The type of the parameter (required for non-body parameters) + * @property `format` - The extending format for the type + * @property `allowEmptyValue` - Whether empty values are allowed + * @property `items` - Schema for array items (required if type is "array") + * @property `collectionFormat` - Format for array parameters + * @property `default` - Default value for the parameter + * @property `maximum` - Maximum value for numbers + * @property `exclusiveMaximum` - Whether maximum is exclusive + * @property `minimum` - Minimum value for numbers + * @property `exclusiveMinimum` - Whether minimum is exclusive + * @property `maxLength` - Maximum length for strings + * @property `minLength` - Minimum length for strings + * @property `pattern` - Regular expression pattern for strings + * @property `maxItems` - Maximum number of items in arrays + * @property `minItems` - Minimum number of items in arrays + * @property `uniqueItems` - Whether array items must be unique + * @property `enum` - Array of valid values + * @property `multipleOf` - Value must be a multiple of this number + * @property `x-${string}` - Specification Extensions + * + * @note + * Path parameters are always required. The type property is required for + * non-body parameters. File type is only valid for formData parameters. + * + * ----- + * Examples + * ----- + * + * @example (query parameter): + * ```ts + * const queryParam: NonBodyParameter = { + * name: "limit", + * in: "query", + * description: "Maximum number of items to return", + * required: false, + * type: "integer", + * format: "int32", + * default: 10 + * }; + * ``` + * + * @example (path parameter): + * ```ts + * const pathParam: NonBodyParameter = { + * name: "id", + * in: "path", + * description: "User ID", + * required: true, + * type: "string" + * }; + * ``` + * + * @example (header parameter): + * ```ts + * const headerParam: NonBodyParameter = { + * name: "X-API-Key", + * in: "header", + * description: "API key for authentication", + * required: true, + * type: "string" + * }; + * ``` + * + * @example (form data parameter): + * ```ts + * const formParam: NonBodyParameter = { + * name: "file", + * in: "formData", + * description: "File to upload", + * required: true, + * type: "file" + * }; + * ``` + */ +export interface NonBodyParameter extends Extension { + /** + * The name of the parameter. Parameter names are case sensitive. + * - If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object + * - For all other cases, the name corresponds to the parameter name used by the in property + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - name} + * + * @example "id" + * @example "limit" + * @example "user" + */ + name: string; + + /** + * The location of the parameter. Possible values are "query", "header", "path", or "formData". + * + * - **query**: Parameters that are appended to the URL. For example, in `/users?role=admin`, the role query parameter has the value admin. + * - **header**: Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive. + * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. + * - **formData**: Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded or multipart/form-data is used as the content type of the request. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - in} + * + * @example "query" + * @example "path" + * @example "header" + * @example "formData" + */ + in: "query" | "header" | "path" | "formData"; + + /** + * A brief description of the parameter. This could contain examples of use. + * GFM syntax can be used for rich text representation. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - description} + * + * @example "The user ID" + * @example "Maximum number of items to return (default: 10)" + */ + description?: string; + + /** + * Determines whether this parameter is mandatory. If the parameter is in "path", + * this property is required and its value MUST be true. Otherwise, the property + * MAY be included and its default value is false. + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - required} + * + * @default false + * @example true + */ + required?: boolean; + + /** + * The type of the parameter. Since the parameter is not located at the request body, + * it is limited to simple types (that is, not an object). The value MUST be one of + * "string", "number", "integer", "boolean", "array" or "file". If type is "file", + * the consumes MUST be either "multipart/form-data", "application/x-www-form-urlencoded" + * or both and the parameter MUST be in "formData". + * + * @see {@link https://swagger.io/specification/v2/#parameter-object | Swagger 2.0 Specification - type} + * + * @example "string" + * @example "integer" + * @example "array" + * @example "file" + */ + type: "string" | "number" | "integer" | "boolean" | "array" | "file"; + + /** + * The extending format for the previously mentioned type. See Data Type Formats + * for further details. + * + * @example "int32" + * @example "date" + * @example "email" + */ + format?: string; + + /** + * Sets the ability to pass empty-valued parameters. This is valid only for either + * query or formData parameters and allows you to send a parameter with a name only + * or an empty value. Default value is false. + * + * @default false + * @example true + */ + allowEmptyValue?: boolean; + + /** + * Required if type is "array". Describes the type of items in the array. + * + * @example { type: "string" } + * @example { type: "integer", format: "int32" } + */ + items?: Items; + + /** + * Determines the format of the array if type array is used. Possible values are: + * - csv: comma separated values foo,bar + * - ssv: space separated values foo bar + * - tsv: tab separated values foo\tbar + * - pipes: pipe separated values foo|bar + * - multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz + * + * @default "csv" + * @example "multi" + */ + collectionFormat?: "csv" | "ssv" | "tsv" | "pipes" | "multi"; + + /** + * Declares the value of the parameter that the server will use if none is provided. + * This value MUST conform to the defined type for this parameter. + * + * @example "defaultValue" + * @example 10 + */ + default?: unknown; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 + * + * @example 100 + */ + maximum?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 + * + * @example false + */ + exclusiveMaximum?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 + * + * @example 0 + */ + minimum?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 + * + * @example false + */ + exclusiveMinimum?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 + * + * @example 100 + */ + maxLength?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 + * + * @example 1 + */ + minLength?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 + * + * @example "^[a-zA-Z0-9]+$" + */ + pattern?: string; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 + * + * @example 10 + */ + maxItems?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 + * + * @example 1 + */ + minItems?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 + * + * @example true + */ + uniqueItems?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 + * + * @example ["option1", "option2", "option3"] + */ + enum?: unknown[]; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 + * + * @example 2 + */ + multipleOf?: number; +} + +/** + * Paths Object + * + * Holds the relative paths to the individual endpoints. The path is appended to the + * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints. + * + * @see https://swagger.io/specification/v2/#paths-object + * @example + * ```typescript + * const paths: Paths = { + * "/pets": { + * "get": { + * "description": "Returns all pets from the system that the user has access to", + * "produces": ["application/json"], + * "responses": { + * "200": { + * "description": "A list of pets.", + * "schema": { + * "type": "array", + * "items": { + * "$ref": "#/definitions/pet" + * } + * } + * } + * } + * } + * } + * } + * ``` + */ +export type Paths = Record; + +/** + * Items Object + * + * A limited subset of JSON-Schema's items object. It is used by parameter definitions + * that are not located in "body". + * + * @see https://swagger.io/specification/v2/#items-object + * @example + * ```typescript + * const items: Items = { + * type: "string", + * minLength: 2 + * } + * ``` + */ +export interface Items extends Extension { + /** + * The internal type of the array. The value MUST be one of "string", "number", + * "integer", "boolean", or "array". Files and models are not allowed. + * + * @example "string" + * @example "integer" + * @example "array" + */ + type: string; + + /** + * The extending format for the previously mentioned type. See Data Type Formats + * for further details. + * + * @example "int32" + * @example "date" + * @example "email" + */ + format?: string; + + /** + * Required if type is "array". Describes the type of items in the array. + * + * @example { type: "string" } + * @example { type: "integer", format: "int32" } + */ + items?: Items; + + /** + * Determines the format of the array if type array is used. Possible values are: + * - csv: comma separated values foo,bar + * - ssv: space separated values foo bar + * - tsv: tab separated values foo\tbar + * - pipes: pipe separated values foo|bar + * + * @default "csv" + * @example "multi" + */ + collectionFormat?: "csv" | "ssv" | "tsv" | "pipes"; + + /** + * Declares the value of the item that the server will use if none is provided. + * This value MUST conform to the defined type for the data type. + * + * @example "defaultValue" + * @example 10 + */ + default?: unknown; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 + * + * @example 100 + */ + maximum?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 + * + * @example false + */ + exclusiveMaximum?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 + * + * @example 0 + */ + minimum?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 + * + * @example false + */ + exclusiveMinimum?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 + * + * @example 100 + */ + maxLength?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 + * + * @example 1 + */ + minLength?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 + * + * @example "^[a-zA-Z0-9]+$" + */ + pattern?: string; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 + * + * @example 10 + */ + maxItems?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 + * + * @example 1 + */ + minItems?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 + * + * @example true + */ + uniqueItems?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 + * + * @example ["option1", "option2", "option3"] + */ + enum?: unknown[]; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 + * + * @example 2 + */ + multipleOf?: number; +} + +/** + * Paths Object + * + * Holds the relative paths to the individual endpoints. The path is appended to the + * basePath in order to construct the full URL. The Paths may be empty, due to ACL constraints. + * + * @see https://swagger.io/specification/v2/#paths-object + * @example + * ```typescript + * const paths: Paths = { + * "/pets": { + * "get": { + * "description": "Returns all pets from the system that the user has access to", + * "produces": ["application/json"], + * "responses": { + * "200": { + * "description": "A list of pets.", + * "schema": { + * "type": "array", + * "items": { + * "$ref": "#/definitions/pet" + * } + * } + * } + * } + * } + * } + * } + * ``` + */ + +/** + * Response Object + * + * Describes a single response from an API Operation. A container for the expected + * responses of an operation. The container maps a HTTP response code to the expected + * response. It is not expected from the documentation to necessarily cover all + * possible HTTP response codes because they may not be known in advance. However, + * it is expected from the documentation to cover a successful operation response + * and any known errors. + * + * @see https://swagger.io/specification/v2/#response-object + * @example + * ```typescript + * const response: Response = { + * description: "User successfully retrieved", + * schema: { $ref: "#/definitions/User" }, + * headers: { + * "X-RateLimit-Limit": { + * type: "integer", + * description: "Rate limit for the current period" + * } + * }, + * examples: { + * "application/json": { + * id: 1, + * name: "John Doe", + * email: "john@example.com" + * } + * } + * } + * ``` + */ +export interface Response extends Extension { + /** + * A short description of the response. + * GitHub Flavored Markdown syntax can be used for rich text representation. + * + * See [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) for more information about the syntax. + * This field is required. + * + * @example "User successfully retrieved" + * @example "Bad request - invalid input parameters" + * @example "Internal server error" + */ + description: string; + + /** + * A definition of the response structure. It can be a primitive, an array or an object. + * If this field does not exist, it means no content is returned as part of the response. + * As an extension to the Schema Object, its root type value may also be "file". + * This SHOULD be accompanied by a relevant produces mime-type. + * + * @example { $ref: "#/definitions/User" } + * @example { type: "array", items: { $ref: "#/definitions/User" } } + * @example { type: "string" } + */ + schema?: Schema; + + /** + * A list of headers that are sent with the response. + * + * @example { "X-RateLimit-Limit": { type: "integer", description: "Rate limit" } } + */ + headers?: Record; + + /** + * An example of the response message. This property is not part of the OpenAPI + * specification but is commonly used by tools to provide example responses. + * + * @example { "application/json": { id: 1, name: "John Doe" } } + */ + examples?: Record; +} + +/** + * Header Object + * + * Describes a single header parameter. A list of all headers that are sent with + * the response. The name is used to refer to the respective header definition. + * The value of the header is of type string. + * + * @see https://swagger.io/specification/v2/#header-object + * @example + * ```typescript + * const header: Header = { + * description: "Rate limit for the current period", + * type: "integer", + * format: "int32" + * } + * ``` + */ +export interface Header extends Extension { + /** + * A brief description of the header. GFM syntax can be used for rich text representation. + * + * @example "Rate limit for the current period" + * @example "Content type of the response" + */ + description?: string; + + /** + * The type of the object. The value MUST be one of "string", "number", "integer", + * "boolean", or "array". + * This field is required. + * + * @example "string" + * @example "integer" + * @example "array" + */ + type: string; + + /** + * The extending format for the previously mentioned type. See Data Type Formats + * for further details. + * + * @example "int32" + * @example "date" + * @example "email" + */ + format?: string; + + /** + * Required if type is "array". Describes the type of items in the array. + * + * @example { type: "string" } + * @example { type: "integer", format: "int32" } + */ + items?: Items; + + /** + * Determines the format of the array if type array is used. Possible values are: + * - csv: comma separated values foo,bar + * - ssv: space separated values foo bar + * - tsv: tab separated values foo\tbar + * - pipes: pipe separated values foo|bar + * + * @default "csv" + * @example "multi" + */ + collectionFormat?: "csv" | "ssv" | "tsv" | "pipes"; + + /** + * Declares the value of the header that the server will use if none is provided. + * This value MUST conform to the defined type for the header. + * + * @example "defaultValue" + * @example 10 + */ + default?: unknown; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 + * + * @example 100 + */ + maximum?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 + * + * @example false + */ + exclusiveMaximum?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 + * + * @example 0 + */ + minimum?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 + * + * @example false + */ + exclusiveMinimum?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 + * + * @example 100 + */ + maxLength?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 + * + * @example 1 + */ + minLength?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 + * + * @example "^[a-zA-Z0-9]+$" + */ + pattern?: string; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 + * + * @example 10 + */ + maxItems?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 + * + * @example 1 + */ + minItems?: number; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 + * + * @example true + */ + uniqueItems?: boolean; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 + * + * @example ["option1", "option2", "option3"] + */ + enum?: unknown[]; + + /** + * See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 + * + * @example 2 + */ + multipleOf?: number; +} + +export type Parameter = BodyParameter | NonBodyParameter; diff --git a/2.0.0/references.ts b/2.0/references.ts similarity index 77% rename from 2.0.0/references.ts rename to 2.0/references.ts index a3c0c81..7a9c0be 100644 --- a/2.0.0/references.ts +++ b/2.0/references.ts @@ -1,4 +1,4 @@ -import type { Extension } from "./extensions" +import type { Extension } from "./extensions"; /** * ----- @@ -6,9 +6,9 @@ import type { Extension } from "./extensions" * ----- * * A simple object to allow referencing other definitions in the specification. - * It can be used to reference parameters and responses that are defined at the - * top level for reuse. The Reference Object is a JSON Reference that uses a - * JSON Pointer as its value. For this specification, only canonical dereferencing + * It can be used to reference parameters and responses that are defined at the + * top level for reuse. The Reference Object is a JSON Reference that uses a + * JSON Pointer as its value. For this specification, only canonical dereferencing * is supported. * * JSON References enable reusability and modularity in API specifications by @@ -25,7 +25,7 @@ import type { Extension } from "./extensions" * Fields * ----- * - * @key `$ref` - The reference string. This field is required. + * @property `$ref` - The reference string. This field is required. * * @note * The reference string follows JSON Pointer syntax and can reference: @@ -82,24 +82,24 @@ import type { Extension } from "./extensions" * ``` */ export interface BaseReference { - /** - * The reference string. This field is required. - * - * The reference string follows JSON Pointer syntax and can reference: - * - Definitions within the same document using "#/definitions/Name" - * - Parameters within the same document using "#/parameters/Name" - * - Responses within the same document using "#/responses/Name" - * - External files using relative or absolute URLs - * - Specific parts of external files using fragment identifiers - * - * @example "#/definitions/Pet" - * @example "#/parameters/skipParam" - * @example "#/responses/NotFound" - * @example "Pet.json" - * @example "definitions.json#/Pet" - * @example "https://api.example.com/schemas/User.json" - */ - $ref: string + /** + * The reference string. This field is required. + * + * The reference string follows JSON Pointer syntax and can reference: + * - Definitions within the same document using "#/definitions/Name" + * - Parameters within the same document using "#/parameters/Name" + * - Responses within the same document using "#/responses/Name" + * - External files using relative or absolute URLs + * - Specific parts of external files using fragment identifiers + * + * @example "#/definitions/Pet" + * @example "#/parameters/skipParam" + * @example "#/responses/NotFound" + * @example "Pet.json" + * @example "definitions.json#/Pet" + * @example "https://api.example.com/schemas/User.json" + */ + $ref: string; } /** diff --git a/2.0/schema.ts b/2.0/schema.ts new file mode 100644 index 0000000..4ae6f01 --- /dev/null +++ b/2.0/schema.ts @@ -0,0 +1,316 @@ +import type { + ArraySchema, + BooleanSchema, + FileSchema, + IntegerSchema, + NumberSchema, + ObjectSchema, + StringSchema, +} from "./data-types"; +import type { BaseReference } from "./references"; +import type { XMLObject } from "./xml"; + +/** + * ----- + * Schema Object (Swagger 2.0) + * ----- + * + * The Schema Object allows the definition of input and output data types. + * These types can be objects, but also primitives and arrays. This object + * is a subset of JSON Schema Specification Draft 4 and uses the same + * formatting rules (sections 9-11). + * + * In Swagger 2.0, this is a limited subset of JSON Schema. Here we model it + * as a discriminated union that enforces mutual-exclusion and co-occurrence + * rules as specified in the Swagger 2.0 specification. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#schema-object | Swagger 2.0 Schema Object} | + * | 2.0 | {@link https://swagger.io/specification/v2/#data-types | Swagger 2.0 Data Types} | + * + * ----- + * Schema Types + * ----- + * + * The Schema union includes the following types: + * + * **Reference Schema:** + * @property `$ref` - A reference to a schema (exclusive with other properties) + * @property `description` - A description of the referenced schema + * + * **String Schema:** + * @property `type: "string"` - The type identifier for string schemas + * @property `format` - The format of the string (email, date, uuid, etc.) + * @property `maxLength` - The maximum length of the string + * @property `minLength` - The minimum length of the string + * @property `pattern` - A regular expression pattern the string must match + * @property `enum` - An enumeration of string values + * + * **Number Schema:** + * @property `type: "number"` - The type identifier for number schemas + * @property `format` - The format of the number (float, double) + * @property `multipleOf` - A number that must be a multiple of this value + * @property `maximum` - The maximum value (inclusive) + * @property `exclusiveMaximum` - The maximum value (exclusive) + * @property `minimum` - The minimum value (inclusive) + * @property `exclusiveMinimum` - The minimum value (exclusive) + * @property `enum` - An enumeration of number values + * + * **Integer Schema:** + * @property `type: "integer"` - The type identifier for integer schemas + * @property `format` - The format of the integer (int32, int64) + * @property `multipleOf` - An integer that must be a multiple of this value + * @property `maximum` - The maximum value (inclusive) + * @property `exclusiveMaximum` - The maximum value (exclusive) + * @property `minimum` - The minimum value (inclusive) + * @property `exclusiveMinimum` - The minimum value (exclusive) + * @property `enum` - An enumeration of integer values + * + * **Boolean Schema:** + * @property `type: "boolean"` - The type identifier for boolean schemas + * @property `enum` - An enumeration of boolean values + * + * **File Schema:** + * @property `type: "file"` - The type identifier for file schemas (Swagger 2.0 specific) + * + * **Array Schema:** + * @property `type: "array"` - The type identifier for array schemas + * @property `items` - The schema for array items + * @property `minItems` - The minimum number of items in the array + * @property `maxItems` - The maximum number of items in the array + * @property `uniqueItems` - Whether array items must be unique + * + * **Object Schema:** + * @property `type: "object"` - The type identifier for object schemas + * @property `properties` - A map of property names to their schemas + * @property `required` - An array of required property names + * @property `additionalProperties` - The schema for additional properties + * @property `minProperties` - The minimum number of properties + * @property `maxProperties` - The maximum number of properties + * @property `allOf` - An array of schemas that must all be satisfied + * + * **Common Properties:** + * @property `title` - A short title for the schema + * @property `description` - A description of the schema + * @property `default` - The default value for the schema + * @property `example` - An example value for the schema + * @property `enum` - An enumeration of allowed values + * @property `discriminator` - A discriminator field for polymorphism (Swagger 2.0 specific) + * @property `readOnly` - Whether the property is read-only (Swagger 2.0 specific) + * @property `xml` - XML-specific metadata + * @property `externalDocs` - External documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The Schema Object is a discriminated union that enforces mutual-exclusion and + * co-occurrence rules. When `$ref` is present, no other properties except + * `description` and extensions are allowed. The `file` type is specific to + * Swagger 2.0 and not part of the JSON Schema specification. + * + * ----- + * Examples + * ----- + * + * @example (reference schema): + * ```ts + * const schema: Schema = { + * $ref: "#/definitions/User" + * }; + * ``` + * + * @example (string schema): + * ```ts + * const schema: Schema = { + * type: "string", + * format: "email", + * maxLength: 255 + * }; + * ``` + * + * @example (object schema): + * ```ts + * const schema: Schema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * }, + * required: ["name"] + * }; + * ``` + * + * @example (file schema): + * ```ts + * const schema: Schema = { + * type: "file", + * description: "Image file to upload" + * }; + * ``` + */ +export type Schema = + | StringSchema + | NumberSchema + | IntegerSchema + | BooleanSchema + | FileSchema + | ArraySchema + | ObjectSchema + | BaseReference; + +/** + * ----- + * XML Object + * ----- + * + * A metadata object that allows for more fine-tuned XML model definitions. + * When using arrays, XML element names are not inferred (for singular/plural forms) + * and the name property should be used to add that information. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#xml-object | Swagger 2.0 XML Object} | + * + * ----- + * Examples + * ----- + * + * @example (simple XML): + * ```ts + * const xml: XML = { + * name: "animal", + * namespace: "http://example.com/schema/sample", + * prefix: "sample", + * attribute: false, + * wrapped: true + * }; + * ``` + */ +export type XML = XMLObject; + +/** + * ----- + * Definitions Object + * ----- + * + * An object to hold data types that can be consumed and produced by operations. + * These data types can be primitives, arrays or models. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#definitions-object | Swagger 2.0 Definitions Object} | + * + * ----- + * Examples + * ----- + * + * @example (basic definitions): + * ```ts + * const definitions: Definitions = { + * "Category": { + * "type": "object", + * "properties": { + * "id": { + * "type": "integer", + * "format": "int64" + * }, + * "name": { + * "type": "string" + * } + * } + * }, + * "Tag": { + * "type": "object", + * "properties": { + * "id": { + * "type": "integer", + * "format": "int64" + * }, + * "name": { + * "type": "string" + * } + * } + * } + * }; + * ``` + */ +export type Definitions = Record; + +/** + * ----- + * Parameters Definitions Object + * ----- + * + * An object to hold parameters to be reused across operations. Parameter definitions + * can be referenced to the ones defined here. This does not define global operation parameters. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#parameters-definitions-object | Swagger 2.0 Parameters Definitions Object} | + * + * ----- + * Examples + * ----- + * + * @example (parameter definitions): + * ```ts + * const parameters: ParametersDefinitions = { + * "skipParam": { + * "name": "skip", + * "in": "query", + * "description": "number of items to skip", + * "required": true, + * "type": "integer", + * "format": "int32" + * }, + * "limitParam": { + * "name": "limit", + * "in": "query", + * "description": "max records to return", + * "required": true, + * "type": "integer", + * "format": "int32" + * } + * }; + * ``` + */ +export type ParametersDefinitions = Record; + +/** + * ----- + * Responses Definitions Object + * ----- + * + * An object to hold responses to be reused across operations. Response definitions + * can be referenced to the ones defined here. This does not define global operation responses. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#responses-definitions-object | Swagger 2.0 Responses Definitions Object} | + * + * ----- + * Examples + * ----- + * + * @example (response definitions): + * ```ts + * const responses: ResponsesDefinitions = { + * "NotFound": { + * "description": "Entity not found." + * }, + * "IllegalInput": { + * "description": "Illegal input for operation." + * }, + * "GeneralError": { + * "description": "General Error", + * "schema": { + * "$ref": "#/definitions/GeneralError" + * } + * } + * }; + * ``` + */ +export type ResponsesDefinitions = Record; + +// Re-export types from paths.ts to avoid circular dependencies +import type { Parameter, Response } from "./paths"; diff --git a/2.0/security.ts b/2.0/security.ts new file mode 100644 index 0000000..d96cc56 --- /dev/null +++ b/2.0/security.ts @@ -0,0 +1,236 @@ +import type { Extension } from "./extensions"; + +/** + * Security Scheme Object + * + * Defines a security scheme that can be used by the operations. Supported schemes + * are basic authentication, an API key (either as a header or as a query parameter) + * and OAuth2's common flows (implicit, password, application and access code). + * + * @see https://swagger.io/specification/v2/#security-scheme-object + * @example + * ```typescript + * // API Key authentication + * const apiKeyScheme: SecurityScheme = { + * type: "apiKey", + * name: "X-API-Key", + * in: "header", + * description: "API key for authentication" + * } + * + * // OAuth2 with authorization code flow + * const oauth2Scheme: SecurityScheme = { + * type: "oauth2", + * flow: "accessCode", + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access to resources", + * "write": "Write access to resources" + * } + * } + * + * // Basic authentication + * const basicScheme: SecurityScheme = { + * type: "basic", + * description: "HTTP Basic Authentication" + * } + * ``` + */ +export interface SecurityScheme extends Extension { + /** + * The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2". + * This field is required. + * + * - **basic**: Basic HTTP authentication + * - **apiKey**: API key authentication (header or query parameter) + * - **oauth2**: OAuth 2.0 authentication + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - type} + * + * @example "apiKey" + * @example "oauth2" + * @example "basic" + */ + type: "basic" | "apiKey" | "oauth2"; + + /** + * A short description for security scheme. GFM syntax can be used for rich text representation. + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - description} + * + * @example "API key for authentication" + * @example "OAuth 2.0 with authorization code flow" + */ + description?: string; + + /** + * The name of the header or query parameter to be used. This field is required + * for apiKey type and applies to apiKey type only. + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - name} + * + * @example "X-API-Key" + * @example "Authorization" + */ + name?: string; + + /** + * The location of the API key. This field is required for apiKey type and + * applies to apiKey type only. Valid values are "query" or "header". + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - in} + * + * @example "header" + * @example "query" + */ + in?: "query" | "header"; + + /** + * The flow used by the OAuth2 security scheme. This field is required for + * oauth2 type and applies to oauth2 type only. Valid values are "implicit", + * "password", "application" or "accessCode". + * + * - **implicit**: Implicit flow + * - **password**: Resource owner password credentials flow + * - **application**: Client credentials flow + * - **accessCode**: Authorization code flow + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - flow} + * + * @example "accessCode" + * @example "implicit" + * @example "password" + */ + flow?: "implicit" | "password" | "application" | "accessCode"; + + /** + * The authorization URL to be used for this flow. This SHOULD be in the form of + * a URL. This field is required for oauth2 type and applies to oauth2 type only. + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - authorizationUrl} + * + * @example "https://example.com/oauth/authorize" + * @example "https://api.example.com/oauth/authorize" + */ + authorizationUrl?: string; + + /** + * The token URL to be used for this flow. This SHOULD be in the form of a URL. + * This field is required for oauth2 type and applies to oauth2 type only. + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - tokenUrl} + * + * @example "https://example.com/oauth/token" + * @example "https://api.example.com/oauth/token" + */ + tokenUrl?: string; + + /** + * The available scopes for the OAuth2 security scheme. The key is the scope name + * and the value is a short description of the scope. This field is required for + * oauth2 type and applies to oauth2 type only. + * + * @see {@link https://swagger.io/specification/v2/#security-scheme-object | Swagger 2.0 Specification - scopes} + * + * @example { "read": "Read access to resources", "write": "Write access to resources" } + * @example { "admin": "Administrative access" } + */ + scopes?: Scopes; +} + +/** + * Scopes Object + * + * Lists the available scopes for an OAuth2 security scheme. + * + * @see https://swagger.io/specification/v2/#scopes-object + * @example + * ```typescript + * const scopes: Scopes = { + * "write:pets": "modify pets in your account", + * "read:pets": "read your pets" + * } + * ``` + */ +export interface Scopes { + /** + * Maps between a name of a scope to a short description of it (as the value of the property). + * The key is the scope name and the value is a short description of the scope. + * + * @see {@link https://swagger.io/specification/v2/#scopes-object | Swagger 2.0 Specification - scopes} + * + * @example { "read": "Read access to resources", "write": "Write access to resources" } + * @example { "admin": "Administrative access" } + */ + [scopeName: string]: string; +} + +/** + * Security Requirement Object + * + * Lists the required security schemes to execute this operation. The object can have + * multiple security schemes declared in it which are all required (that is, there is + * a logical AND between the schemes). The name used for each property MUST correspond + * to a security scheme declared in the Security Definitions. + * + * @see https://swagger.io/specification/v2/#security-requirement-object + * @example + * ```typescript + * // Non-OAuth2 Security Requirement + * const nonOAuth2Security: SecurityRequirement = { + * "api_key": [] + * } + * + * // OAuth2 Security Requirement + * const oauth2Security: SecurityRequirement = { + * "petstore_auth": [ + * "write:pets", + * "read:pets" + * ] + * } + * ``` + */ +export interface SecurityRequirement { + /** + * Each name must correspond to a security scheme which is declared in the Security Definitions. + * If the security scheme is of type "oauth2", then the value is a list of scope names + * required for the execution. For other security scheme types, the array MUST be empty. + * + * @see {@link https://swagger.io/specification/v2/#security-requirement-object | Swagger 2.0 Specification - security requirement} + * + * @example { "api_key": [] } + * @example { "oauth2": ["read", "write"] } + */ + [schemeName: string]: string[]; +} + +/** + * Security Definitions Object + * + * A declaration of the security schemes available to be used in the specification. + * This does not enforce the security schemes on the operations and only serves to + * provide the relevant details for each scheme. + * + * @see https://swagger.io/specification/v2/#security-definitions-object + * @example + * ```typescript + * const securityDefinitions: SecurityDefinitions = { + * "api_key": { + * "type": "apiKey", + * "name": "api_key", + * "in": "header" + * }, + * "petstore_auth": { + * "type": "oauth2", + * "authorizationUrl": "http://swagger.io/api/oauth/dialog", + * "flow": "implicit", + * "scopes": { + * "write:pets": "modify pets in your account", + * "read:pets": "read your pets" + * } + * } + * } + * ``` + */ +export type SecurityDefinitions = Record; diff --git a/2.0/spec.ts b/2.0/spec.ts new file mode 100644 index 0000000..38dfb68 --- /dev/null +++ b/2.0/spec.ts @@ -0,0 +1,236 @@ +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +// Import all the major component types +import type { Info } from "./info"; +import type { Paths } from "./paths"; +import type { + Definitions, + ParametersDefinitions, + ResponsesDefinitions, +} from "./schema"; +import type { SecurityDefinitions, SecurityRequirement } from "./security"; +import type { Tag } from "./tags"; + +/** + * Root Swagger 2.0 Schema (Swagger Object) + * + * This is the root document object of the OpenAPI specification. It contains + * all the metadata about the API being described. This object is based on the + * JSON Schema Specification Draft 4 and uses a predefined subset of it. + * + * The Swagger Object is the root of the specification document and contains + * all the information about the API, including its metadata, available paths, + * data models, security schemes, and more. + * + * @see https://swagger.io/specification/v2/#swagger-object + * @example + * ```typescript + * const swagger: Specification = { + * swagger: "2.0", + * info: { + * title: "Swagger Sample App", + * description: "This is a sample server Petstore server.", + * version: "1.0.1" + * }, + * host: "petstore.swagger.io", + * basePath: "/v2", + * schemes: ["https"], + * paths: { + * "/pets": { + * get: { + * summary: "List all pets", + * responses: { + * "200": { + * description: "A list of pets", + * schema: { + * type: "array", + * items: { $ref: "#/definitions/Pet" } + * } + * } + * } + * } + * } + * }, + * definitions: { + * Pet: { + * type: "object", + * properties: { + * id: { type: "integer", format: "int64" }, + * name: { type: "string" }, + * tag: { type: "string" } + * } + * } + * } + * } + * ``` + */ +export type Specification = { + /** + * Specifies the Swagger specification version being used. + * Must be "2.0" for this specification. + * + * @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - swagger} + */ + swagger: "2.0"; + + /** + * Provides metadata about the API. The metadata can be used by the clients + * if needed, and can be presented in the Swagger-UI for convenience. + * + * @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - info} + */ + info: Info; + + /** + * The host (name or IP) serving the API. This MUST be the host only and does + * not include the scheme nor sub-paths. It MAY include a port. If the host + * is not included, the host serving the documentation is to be used + * (including the port). The host does not support path templating. + * + * @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - host} + * + * @example "api.example.com" + * @example "api.example.com:8080" + */ + host?: string; + + /** + * The base path on which the API is served, which is relative to the host. + * If it is not included, the API is served directly under the host. + * The value MUST start with a leading slash (/). The basePath does not + * support path templating. + * + * @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - basePath} + * + * @example "/v1" + * @example "/api/v2" + */ + basePath?: string; + + /** + * The transfer protocol of the API. Values MUST be from the list: + * "http", "https", "ws", "wss". If the schemes is not included, the default + * scheme to be used is the one used to access the specification. + * + * @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - schemes} + * + * @example ["https", "http"] + * @example ["wss"] + */ + schemes?: Array<"http" | "https" | "ws" | "wss">; + + /** + * A list of MIME types the APIs can consume. This is global to all APIs + * but can be overridden on specific API calls. Value MUST be as described + * under Mime Types. + * + * @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - consumes} + * + * @example ["application/json"] + * @example ["application/xml", "application/json"] + */ + consumes?: string[]; + + /** + * A list of MIME types the APIs can produce. This is global to all APIs + * but can be overridden on specific API calls. Value MUST be as described + * under Mime Types. + * + * @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - produces} + * + * @example ["application/json"] + * @example ["application/xml", "application/json"] + */ + produces?: string[]; + + /** + * The available paths and operations for the API. This is the root of the + * Path Item Object. It does not define a path or a basePath, they are defined + * in the Paths Object. A relative path to an individual endpoint. The field + * name MUST begin with a slash. The path is appended to the basePath in order + * to construct the full URL. Path templating is allowed. + * + * @see {@link https://swagger.io/specification/v2/#paths-object | Swagger 2.0 Specification - paths} + * + * @example { "/users": { get: { ... } } } + * @example { "/users/{id}": { get: { ... } } } + */ + paths: Paths; + + /** + * An object to hold data types produced and consumed by operations. + * These data types can be primitives, arrays or models. + * + * @see {@link https://swagger.io/specification/v2/#definitions-object | Swagger 2.0 Specification - definitions} + * + * @example { "User": { type: "object", properties: { ... } } } + */ + definitions?: Definitions; + + /** + * An object to hold parameters that can be used across operations. + * This property does not define global parameters for all operations. + * + * @see {@link https://swagger.io/specification/v2/#parameters-definitions-object | Swagger 2.0 Specification - parameters} + * + * @example { "pageParam": { name: "page", in: "query", type: "integer" } } + */ + parameters?: ParametersDefinitions; + + /** + * An object to hold responses that can be used across operations. + * This property does not define global responses for all operations. + * + * @see {@link https://swagger.io/specification/v2/#responses-definitions-object | Swagger 2.0 Specification - responses} + * + * @example { "NotFound": { description: "Entity not found" } } + */ + responses?: ResponsesDefinitions; + + /** + * Security scheme definitions that can be used by the operations. + * Supported schemes are basic authentication, an API key (either as a header + * or as a query parameter) and OAuth2's common flows (implicit, password, + * application and access code). + * + * @see {@link https://swagger.io/specification/v2/#security-definitions-object | Swagger 2.0 Specification - securityDefinitions} + * + * @example { "api_key": { type: "apiKey", in: "header", name: "X-API-Key" } } + */ + securityDefinitions?: SecurityDefinitions; + + /** + * A declaration of which security schemes are applied for the API as a whole. + * The list of values describes alternative security schemes that can be used + * (that is, there is a logical OR between the security requirements). + * Individual operations can override this definition. + * + * @see {@link https://swagger.io/specification/v2/#security-requirement-object | Swagger 2.0 Specification - security} + * + * @example [{ "api_key": [] }] + * @example [{ "oauth2": ["read", "write"] }] + */ + security?: SecurityRequirement[]; + + /** + * A list of tags used by the specification with additional metadata. + * The order of the tags can be used to reflect on their order by the + * parsing tools. Not all tags that are used by the Operation Object must + * be declared. The tags that are not declared may be organized randomly + * or based on the tools' logic. Each tag name in the list MUST be unique. + * + * @see {@link https://swagger.io/specification/v2/#tag-object | Swagger 2.0 Specification - tags} + * + * @example [{ name: "users", description: "User management" }] + */ + tags?: Tag[]; + + /** + * Additional external documentation. + * + * @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - externalDocs} + * + * @example { description: "Find out more about our API", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; +} & Extension; diff --git a/2.0/status.ts b/2.0/status.ts new file mode 100644 index 0000000..85371be --- /dev/null +++ b/2.0/status.ts @@ -0,0 +1,935 @@ +import type { Response } from "./paths"; + +/** + * Swagger 2.0 Valid HTTP Status Codes + * + * Enumerates individual HTTP status codes (as keys) plus the special `"default"` key, + * per the IANA HTTP Status Code Registry. JSDoc reason phrases and references mirror + * the registry entries. See also RFC 9110 (HTTP Semantics) section mappings. + * + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA: HTTP Status Code Registry} + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html | RFC 9110: HTTP Semantics} + */ +export interface ResponsesMap { + //#region 1xx — Informational + + /** 100 Continue + * + * Indicates that the initial part of the request has been received and the client should continue with the request. + * + * The server has received the request headers and the client should proceed to send the request body. + * + * Used in scenarios where the client needs to send a large request body and wants to confirm the server is ready to receive it before sending the data. Commonly used with `Expect: 100-continue` header for file uploads, API requests with large payloads, or when implementing optimistic request patterns. + * + * The server is ready to process the request and the client can proceed with sending the request body. This prevents unnecessary data transmission if the server would reject the request based on headers alone. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-100-continue | RFC 9110 §15.2.1} + */ + "100"?: Response; + + /** 101 Switching Protocols + * + * Indicates that the server is switching protocols as requested by the client. + * + * The server agrees to change the application protocol within the current connection, typically from HTTP to WebSocket or other protocols. + * + * Primarily used for WebSocket connections where the client sends an `Upgrade: websocket` header and the server responds with 101 to establish the WebSocket connection. Also used for HTTP/2 upgrades, Server-Sent Events (SSE), or other protocol switching scenarios. + * + * The connection will continue using a different protocol. The response headers will contain the new protocol information, and subsequent communication will use the upgraded protocol. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-101-switching-protocols | RFC 9110 §15.2.2} + */ + "101"?: Response; + + /** 102 Processing + * + * Indicates that the server has received and is processing the request, but no response is available yet. + * + * The server has accepted the request and is processing it, but the processing is taking longer than normal and the client should continue waiting. + * + * Primarily used in WebDAV (Web Distributed Authoring and Versioning) environments for long-running operations like file uploads, batch operations, or complex data processing. Helps prevent client timeouts during extended processing periods. + * + * The request is being processed and the client should continue waiting. This prevents timeout issues during long-running operations and provides feedback that the server is actively working on the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2518 | RFC 2518 (WebDAV)} + */ + "102"?: Response; + + /** 103 Early Hints + * + * Provides early hints about the response that will be sent, allowing the client to start processing before the full response is ready. + * + * The server is sending preliminary information about the response headers and resources that will be needed, enabling the client to start optimization processes early. + * + * Used for performance optimization, particularly in web applications where the server can hint about resources (CSS, JavaScript, fonts) that will be needed for the final response. Allows browsers to start preloading resources before the main response is ready, significantly improving perceived performance. + * + * The client can start preparing for the response based on the hints provided. This is especially valuable for web applications where resource preloading can improve user experience. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8297 | RFC 8297} + */ + "103"?: Response; + + /** 104 Upload Resumption Supported — TEMPORARY + * + * Indicates that the server supports resumable uploads for the requested resource. + * + * The server is indicating that it can handle interrupted uploads and allows the client to resume uploading from where it left off. + * + * Used in file upload scenarios where large files might be interrupted due to network issues, browser crashes, or other problems. Enables clients to resume uploads without starting over, improving reliability for large file transfers and reducing bandwidth waste. + * + * The client can implement resumable upload logic, typically using range requests or specialized upload protocols. This is particularly valuable for mobile applications and unreliable network conditions. + * + * @note Temporary registration; see IANA entry for current status/expiry. + * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-resumable-upload-05 | draft-ietf-httpbis-resumable-upload-05} + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA registry} + */ + "104"?: Response; + + //#endregion + + //#region 2xx — Success + + /** 200 OK + * + * Indicates that the request has succeeded and the response contains the requested data. + * + * The request was processed successfully and the response body contains the requested resource or data. + * + * The most common success response for GET requests, API endpoints that return data, and successful operations. Used for retrieving resources, executing queries, and any operation that completes successfully with data to return. + * + * The operation completed successfully and the response body contains the requested information. This is the standard success response for most API operations. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok | RFC 9110 §15.3.1} + */ + "200"?: Response; + + /** 201 Created + * + * Indicates that the request has succeeded and a new resource has been created as a result. + * + * The request was processed successfully and resulted in the creation of a new resource. The response typically includes the location of the newly created resource. + * + * Used for POST requests that create new resources (users, posts, files, etc.). The response should include a `Location` header pointing to the newly created resource. Common in REST APIs for resource creation operations. + * + * A new resource was successfully created and the response contains information about the created resource, typically including its ID and location. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-201-created | RFC 9110 §15.3.2} + */ + "201"?: Response; + + /** 202 Accepted + * + * Indicates that the request has been accepted for processing, but the processing has not been completed. + * + * The request was valid and accepted, but the server will process it asynchronously. The processing may or may not eventually succeed. + * + * Used for asynchronous operations like background jobs, batch processing, email sending, or any operation that takes time to complete. The client should not assume the operation succeeded based on this response alone. + * + * The request was accepted and is being processed asynchronously. The client should check the status separately or wait for a callback/webhook to know the final result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted | RFC 9110 §15.3.3} + */ + "202"?: Response; + + /** 203 Non-Authoritative Information + * + * Indicates that the request was successful, but the information returned is from a transformed or cached version of the original resource. + * + * The response is successful but the data may have been modified by a transforming proxy or cache, and may not be the authoritative version. + * + * Used when responses come from caches, proxies, or transformation services where the data might be slightly different from the original. Common in CDN scenarios or when data is processed through middleware. + * + * The request succeeded but the response data may not be the most current or authoritative version. The client should be aware that the data might be cached or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-203-non-authoritative-informat | RFC 9110 §15.3.4} + */ + "203"?: Response; + + /** 204 No Content + * + * Indicates that the request has succeeded but there is no content to return in the response body. + * + * The request was processed successfully but the response body is intentionally empty. The client should not expect any content. + * + * Used for DELETE operations, PUT requests that don't return data, or any operation where success is indicated by the absence of content. Common in REST APIs for operations that modify state without returning data. + * + * The operation completed successfully but no data is returned. The client should not attempt to parse a response body. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-204-no-content | RFC 9110 §15.3.5} + */ + "204"?: Response; + + /** 205 Reset Content + * + * Indicates that the request has succeeded and the client should reset the document view that caused the request to be sent. + * + * The request was processed successfully and the client should clear any form data or reset the user interface state. + * + * Used in web applications where form submissions should clear the form after successful processing, or when the client needs to reset its state. Common in form handling and user interface operations. + * + * The operation succeeded and the client should reset its current state, typically clearing forms or resetting the user interface. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-205-reset-content | RFC 9110 §15.3.6} + */ + "205"?: Response; + + /** 206 Partial Content + * + * Indicates that the server is delivering only part of the resource due to a range request. + * + * The request included a Range header and the server is returning only the requested portion of the resource, along with information about the range delivered. + * + * Used for resumable downloads, video streaming, large file transfers, and any scenario where the client requests a specific portion of a resource. Enables efficient handling of large files and interrupted downloads. + * + * The response contains only a portion of the requested resource. The client should expect partial content and may need to make additional requests for the complete resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-206-partial-content | RFC 9110 §15.3.7} + */ + "206"?: Response; + + /** 207 Multi-Status + * + * Indicates that multiple independent operations might have been performed, and the status of each operation is reported in the response body. + * + * The response contains multiple status codes for different operations, typically in XML format with individual operation results. + * + * Used in WebDAV environments for batch operations, bulk file operations, or any scenario where multiple independent operations are performed in a single request. Common in file management systems and collaborative editing platforms. + * + * Multiple operations were attempted and the response contains the status of each individual operation. The client should parse the response body to determine which operations succeeded or failed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "207"?: Response; + + /** 208 Already Reported + * + * Indicates that the members of a DAV binding have already been enumerated in a previous response to this request, and are not being included again. + * + * Used in WebDAV to avoid repeating the same information in a multi-status response when the same binding has already been reported. + * + * Used in WebDAV environments to optimize responses by avoiding duplicate information in multi-status responses. Helps reduce response size and improve performance in complex file system operations. + * + * The information for this binding has already been reported in a previous part of the response. The client should not expect additional information for this specific binding. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "208"?: Response; + + /** 226 IM Used + * + * Indicates that the server has fulfilled a request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance. + * + * The response represents the result of applying instance manipulations (like delta encoding) to the current resource instance. + * + * Used in scenarios involving delta encoding, instance manipulations, or when the response represents a transformed version of the resource. Common in content delivery networks and systems that optimize data transmission. + * + * The response contains a manipulated version of the resource, typically optimized for transmission. The client should be aware that the data has been processed or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc3229 | RFC 3229} + */ + "226"?: Response; + + //#endregion + + //#region 3xx — Redirection + + /** 300 Multiple Choices + * + * Indicates that the request has multiple possible responses and the client should choose one. + * + * The server has multiple representations of the requested resource and the client must choose which one to use. + * + * Used when content negotiation results in multiple valid options, such as different formats (JSON, XML, HTML) or different languages. The response typically includes a list of available options with their characteristics. + * + * The client should examine the available options and make a choice, typically by sending another request with more specific preferences or headers. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-300-multiple-choices | RFC 9110 §15.4.1} + */ + "300"?: Response; + + /** 301 Moved Permanently + * + * Indicates that the requested resource has been permanently moved to a new location. + * + * The resource has been permanently relocated and all future requests should be directed to the new URL provided in the Location header. + * + * Used when resources are permanently relocated, such as when changing domain names, restructuring URLs, or moving content to new locations. Browsers and clients should update their bookmarks and caches. + * + * The resource has moved permanently and the client should update all references to use the new URL. Search engines and caches should update their indexes. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-301-moved-permanently | RFC 9110 §15.4.2} + */ + "301"?: Response; + + /** 302 Found + * + * Indicates that the requested resource has been temporarily moved to a different location. + * + * The resource is temporarily available at a different URL, but the original URL should continue to be used for future requests. + * + * Used for temporary redirects such as maintenance pages, temporary content moves, or when the resource is temporarily unavailable at the original location. The original URL remains valid. + * + * The resource is temporarily at a different location. The client should follow the redirect but continue using the original URL for future requests. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-302-found | RFC 9110 §15.4.3} + */ + "302"?: Response; + + /** 303 See Other + * + * Indicates that the response to the request can be found at a different URL and should be retrieved using a GET request. + * + * The request was processed but the response is available at a different location, and the client should use GET to retrieve it. + * + * Used in POST-redirect-GET patterns, form submissions that redirect to a results page, or when the response to a POST request should be retrieved via GET. Common in web applications for avoiding duplicate form submissions. + * + * The client should make a GET request to the provided URL to retrieve the response. This prevents duplicate submissions and provides a clean URL for the result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-303-see-other | RFC 9110 §15.4.4} + */ + "303"?: Response; + + /** 304 Not Modified + * + * Indicates that the resource has not been modified since the last request, so the cached version can be used. + * + * The resource has not changed since the last request, and the client can use its cached version. No response body is included. + * + * Used for caching optimization when the client sends conditional headers (If-Modified-Since, If-None-Match). Reduces bandwidth usage and improves performance by avoiding unnecessary data transfer. + * + * The resource has not changed and the client should use its cached version. This is an optimization response that saves bandwidth and improves performance. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-304-not-modified | RFC 9110 §15.4.5} + */ + "304"?: Response; + + /** 305 Use Proxy + * + * Indicates that the requested resource must be accessed through the proxy specified in the Location header. + * + * The client must use the specified proxy to access the resource. This response is rarely used in modern web applications. + * + * Used in corporate environments or specific network configurations where resources must be accessed through a particular proxy server. Mostly deprecated in modern web development. + * + * The client should use the specified proxy to access the resource. This is rarely encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy | RFC 9110 §15.4.6} + */ + "305"?: Response; + + /** 306 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code was previously used but is now reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-306-unused | RFC 9110 §15.4.7} + */ + "306"?: Response; + + /** 307 Temporary Redirect + * + * Indicates that the requested resource has been temporarily moved to a different location, and the request method should be preserved. + * + * The resource is temporarily available at a different URL, and the client should repeat the request using the same method to the new location. + * + * Used for temporary redirects where the HTTP method (POST, PUT, DELETE) should be preserved. Common in API versioning, temporary maintenance, or when resources are temporarily relocated. + * + * The resource is temporarily at a different location and the client should repeat the same request method to the new URL. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-307-temporary-redirect | RFC 9110 §15.4.8} + */ + "307"?: Response; + + /** 308 Permanent Redirect + * + * Indicates that the requested resource has been permanently moved to a different location, and the request method should be preserved. + * + * The resource has been permanently relocated and the client should use the new URL for all future requests, preserving the original HTTP method. + * + * Used for permanent redirects where the HTTP method should be preserved, such as when moving APIs to new endpoints or restructuring resource URLs. Common in API versioning and permanent relocations. + * + * The resource has moved permanently and the client should update all references to use the new URL while preserving the original HTTP method. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-308-permanent-redirect | RFC 9110 §15.4.9} + */ + "308"?: Response; + + //#endregion + + //#region 4xx — Client Error + + /** 400 Bad Request + * + * Indicates that the server cannot process the request due to a client error. + * + * The request syntax is invalid, malformed, or contains incorrect parameters that the server cannot understand or process. + * + * Used for validation errors, malformed JSON, missing required fields, invalid parameter values, or any client-side error that prevents the server from processing the request. Common in API validation scenarios. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request | RFC 9110 §15.5.1} + */ + "400"?: Response; + + /** 401 Unauthorized + * + * Indicates that the request requires authentication and the client has not provided valid credentials. + * + * The request lacks valid authentication credentials or the provided credentials are invalid, expired, or insufficient. + * + * Used when authentication is required but not provided, when login credentials are invalid, or when the authentication token has expired. Common in protected API endpoints and user authentication flows. + * + * The client needs to authenticate before accessing the resource. The response should include authentication challenge headers (WWW-Authenticate) indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized | RFC 9110 §15.5.2} + */ + "401"?: Response; + + /** 402 Payment Required + * + * Indicates that the request requires payment before it can be processed. + * + * The request cannot be fulfilled because payment is required. This status code is reserved for future use in digital payment systems. + * + * Used in payment-required scenarios, subscription services, or when access to a resource requires payment. Common in freemium models, paid API access, or premium content services. + * + * The client needs to provide payment information or complete a payment process before accessing the resource. The response should include information about how to make the payment. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required | RFC 9110 §15.5.3} + */ + "402"?: Response; + + /** 403 Forbidden + * + * Indicates that the server understood the request but refuses to authorize it. + * + * The client is authenticated but does not have permission to access the requested resource or perform the requested action. + * + * Used when the user is logged in but lacks the necessary permissions, when access is restricted based on user roles, or when the resource is not accessible to the current user. Common in authorization and access control scenarios. + * + * The client is authenticated but not authorized to access the resource. The client should not retry the request without additional permissions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden | RFC 9110 §15.5.4} + */ + "403"?: Response; + + /** 404 Not Found + * + * Indicates that the requested resource could not be found on the server. + * + * The server cannot find the requested resource at the specified URL, or the resource does not exist. + * + * Used when a resource doesn't exist, when the URL is incorrect, or when the requested item has been deleted. Common in web applications for missing pages, deleted content, or non-existent API endpoints. + * + * The requested resource does not exist. The client should verify the URL or check if the resource has been moved or deleted. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found | RFC 9110 §15.5.5} + */ + "404"?: Response; + + /** 405 Method Not Allowed + * + * Indicates that the HTTP method used in the request is not allowed for the requested resource. + * + * The resource exists but the HTTP method (GET, POST, PUT, DELETE, etc.) is not supported for this particular resource. + * + * Used when a resource only supports certain HTTP methods, such as a read-only endpoint that doesn't allow POST requests, or when the method is not implemented for the specific resource. Common in REST API design. + * + * The HTTP method is not allowed for this resource. The response should include an Allow header listing the permitted methods. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-405-method-not-allowed | RFC 9110 §15.5.6} + */ + "405"?: Response; + + /** 406 Not Acceptable + * + * Indicates that the server cannot produce a response matching the client's Accept headers. + * + * The server cannot generate a response in any of the formats requested by the client's Accept headers. + * + * Used when the client requests a specific content type (JSON, XML, HTML) that the server cannot provide, or when content negotiation fails. Common in API versioning and content type mismatches. + * + * The server cannot provide the requested content type. The client should check the Accept headers or request a different format. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable | RFC 9110 §15.5.7} + */ + "406"?: Response; + + /** 407 Proxy Authentication Required + * + * Indicates that the client must authenticate with the proxy server before the request can be processed. + * + * The proxy server requires authentication before it will forward the request to the destination server. + * + * Used in corporate environments or networks where proxy authentication is required. Common in enterprise networks, VPN connections, or when accessing resources through authenticated proxies. + * + * The client needs to authenticate with the proxy server. The response should include Proxy-Authenticate headers indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-req | RFC 9110 §15.5.8} + */ + "407"?: Response; + + /** 408 Request Timeout + * + * Indicates that the server timed out while waiting for the request from the client. + * + * The server did not receive a complete request within the time it was prepared to wait. + * + * Used when the client takes too long to send the complete request, when network issues cause delays, or when the server has a timeout policy for request processing. Common in slow network conditions or when clients fail to send complete requests. + * + * The request timed out and the client should retry the request. The client may need to optimize the request or check network connectivity. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-408-request-timeout | RFC 9110 §15.5.9} + */ + "408"?: Response; + + /** 409 Conflict + * + * Indicates that the request conflicts with the current state of the resource. + * + * The request cannot be completed due to a conflict with the current state of the resource, such as a version mismatch or concurrent modification. + * + * Used when trying to create a resource that already exists, when there's a version conflict in concurrent editing, or when the request conflicts with business rules. Common in collaborative editing, version control, and resource creation scenarios. + * + * The request conflicts with the current state of the resource. The client should resolve the conflict before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict | RFC 9110 §15.5.10} + */ + "409"?: Response; + + /** 410 Gone + * + * Indicates that the requested resource is no longer available and will not be available again. + * + * The resource has been permanently removed and will not be restored. This is different from 404, which indicates the resource was never found. + * + * Used when content has been permanently deleted, when resources have been removed and will not be restored, or when temporary content has expired. Common in content management systems and temporary resource scenarios. + * + * The resource has been permanently removed and will not be available again. The client should not retry the request and should update any references to this resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-410-gone | RFC 9110 §15.5.11} + */ + "410"?: Response; + + /** 411 Length Required + * + * Indicates that the server requires a Content-Length header in the request. + * + * The server cannot process the request without knowing the exact length of the request body. + * + * Used when the server needs to know the exact size of the request body before processing, such as for file uploads, large data transfers, or when implementing specific security measures. Common in file upload scenarios and certain API endpoints. + * + * The client must include a Content-Length header in the request. The client should retry the request with the proper Content-Length header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-411-length-required | RFC 9110 §15.5.12} + */ + "411"?: Response; + + /** 412 Precondition Failed + * + * Indicates that one or more preconditions in the request headers were not met. + * + * The server cannot meet the conditions specified in the request headers, such as If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-Since. + * + * Used in conditional requests where the client specifies conditions that must be met, such as version checking, cache validation, or optimistic concurrency control. Common in collaborative editing and caching scenarios. + * + * The preconditions in the request were not met. The client should check the conditions and retry the request with updated preconditions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-412-precondition-failed | RFC 9110 §15.5.13} + */ + "412"?: Response; + + /** 413 Content Too Large + * + * Indicates that the request payload is too large for the server to process. + * + * The request body exceeds the server's maximum allowed size limit. + * + * Used when file uploads exceed size limits, when request bodies are too large for processing, or when the server has configured size restrictions. Common in file upload scenarios and API rate limiting. + * + * The request payload is too large. The client should reduce the size of the request body or split it into smaller chunks. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-413-content-too-large | RFC 9110 §15.5.14} + */ + "413"?: Response; + + /** 414 URI Too Long + * + * Indicates that the URI provided in the request is too long for the server to process. + * + * The URL exceeds the server's maximum allowed length limit. + * + * Used when URLs are too long due to excessive query parameters, when GET requests contain too much data in the URL, or when the server has configured URI length restrictions. Common in search APIs and parameter-heavy requests. + * + * The URI is too long. The client should shorten the URL or use POST instead of GET for large amounts of data. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-414-uri-too-long | RFC 9110 §15.5.15} + */ + "414"?: Response; + + /** 415 Unsupported Media Type + * + * Indicates that the server cannot process the request because the media type is not supported. + * + * The server cannot process the request body because the Content-Type is not supported or recognized. + * + * Used when the client sends data in an unsupported format, when the server only accepts specific content types, or when there's a mismatch between the expected and actual content type. Common in API endpoints with strict content type requirements. + * + * The content type is not supported. The client should check the API documentation for supported content types and retry with the correct Content-Type header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type | RFC 9110 §15.5.16} + */ + "415"?: Response; + + /** 416 Range Not Satisfiable + * + * Indicates that the server cannot satisfy the range request specified in the Range header. + * + * The requested range is not valid for the resource, either because the range is beyond the resource size or the resource doesn't support range requests. + * + * Used when range requests are invalid, when the requested range exceeds the resource size, or when the resource doesn't support partial content requests. Common in file download scenarios and media streaming. + * + * The range request is not satisfiable. The client should check the range specification or request the full resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-416-range-not-satisfiable | RFC 9110 §15.5.17} + */ + "416"?: Response; + + /** 417 Expectation Failed + * + * Indicates that the server cannot meet the requirements of the Expect header. + * + * The server cannot fulfill the expectations specified in the Expect header, typically when the server cannot handle the 100-continue expectation. + * + * Used when the server cannot handle the Expect: 100-continue header, when the server doesn't support the expected behavior, or when there's a mismatch between client expectations and server capabilities. Common in HTTP/1.1 implementations. + * + * The server cannot meet the expectations in the request. The client should retry without the Expect header or adjust the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-417-expectation-failed | RFC 9110 §15.5.18} + */ + "417"?: Response; + + /** 418 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code is reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-418-unused | RFC 9110 §15.5.19} + */ + "418"?: Response; + + /** 421 Misdirected Request + * + * Indicates that the request was directed to a server that is not able to produce a response. + * + * The request was sent to a server that cannot handle it, typically due to HTTP/2 connection reuse issues or server configuration problems. + * + * Used in HTTP/2 environments when a request is sent to the wrong server due to connection reuse, when there are server configuration issues, or when the request cannot be processed by the current server instance. Common in load balancing scenarios. + * + * The request was sent to the wrong server. The client should retry the request, which may be routed to a different server. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-request | RFC 9110 §15.5.20} + */ + "421"?: Response; + + /** 422 Unprocessable Content + * + * Indicates that the request is well-formed but contains semantic errors that prevent processing. + * + * The request syntax is correct but the server cannot process the request due to semantic errors, such as validation failures or business rule violations. + * + * Used for validation errors, business rule violations, or when the request is syntactically correct but logically invalid. Common in API validation scenarios where the request format is correct but the data is invalid. + * + * The request is well-formed but contains semantic errors. The client should fix the data and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content | RFC 9110 §15.5.21} + */ + "422"?: Response; + + /** 423 Locked + * + * Indicates that the requested resource is locked and cannot be modified. + * + * The resource is locked by another process or user and cannot be accessed or modified at this time. + * + * Used in WebDAV environments for file locking, collaborative editing scenarios, or when resources are temporarily locked for maintenance. Common in document management systems and collaborative editing platforms. + * + * The resource is locked and cannot be accessed. The client should wait and retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "423"?: Response; + + /** 424 Failed Dependency + * + * Indicates that the request failed because it depended on another request that also failed. + * + * The request cannot be completed because it depends on another operation that failed, typically in batch or multi-part operations. + * + * Used in WebDAV environments for batch operations where one operation depends on another, or in complex workflows where operations have dependencies. Common in file management systems and collaborative editing scenarios. + * + * The request failed due to a dependency failure. The client should check the dependencies and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "424"?: Response; + + /** 425 Too Early + * + * Indicates that the server is unwilling to process the request because it might be replayed. + * + * The server is concerned that the request might be replayed and is unwilling to process it at this time, typically due to timing or security concerns. + * + * Used in scenarios where request replay is a security concern, such as in early data scenarios or when the server needs to prevent replay attacks. Common in security-sensitive applications and protocols. + * + * The server is unwilling to process the request due to replay concerns. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8470 | RFC 8470} + */ + "425"?: Response; + + /** 426 Upgrade Required + * + * Indicates that the server requires the client to upgrade to a different protocol. + * + * The server requires the client to use a different protocol version or upgrade to a newer version to access the resource. + * + * Used when the server requires protocol upgrades, when the client is using an outdated protocol version, or when the server only supports newer protocol versions. Common in API versioning and protocol migration scenarios. + * + * The client must upgrade to a different protocol version. The response should include upgrade information. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-426-upgrade-required | RFC 9110 §15.5.22} + */ + "426"?: Response; + + /** 428 Precondition Required + * + * Indicates that the server requires the request to include certain preconditions. + * + * The server requires the client to include specific preconditions in the request headers before it will process the request. + * + * Used when the server requires specific preconditions for security or consistency reasons, such as requiring If-Match headers for optimistic concurrency control or other conditional headers. Common in collaborative editing and version control scenarios. + * + * The server requires specific preconditions. The client should include the required preconditions and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "428"?: Response; + + /** 429 Too Many Requests + * + * Indicates that the client has sent too many requests in a given time period and should slow down. + * + * The client has exceeded the rate limit and the server is refusing to process additional requests until the rate limit resets. + * + * Used for rate limiting, API throttling, and preventing abuse. Common in API endpoints that need to control request frequency, prevent spam, or manage resource usage. Often includes retry-after headers. + * + * The client has exceeded the rate limit and should slow down. The client should wait before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "429"?: Response; + + /** 431 Request Header Fields Too Large + * + * Indicates that the server is unwilling to process the request because the header fields are too large. + * + * The request headers exceed the server's maximum allowed size limit. + * + * Used when request headers are too large, when there are too many headers, or when individual headers exceed size limits. Common in scenarios with large authentication tokens or excessive header data. + * + * The request headers are too large. The client should reduce the size of the headers and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "431"?: Response; + + /** 451 Unavailable For Legal Reasons + * + * Indicates that the requested resource is unavailable due to legal reasons. + * + * The resource is not available due to legal restrictions, such as censorship, court orders, or regulatory requirements. + * + * Used when content is blocked due to legal restrictions, when resources are unavailable in certain jurisdictions, or when there are regulatory compliance issues. Common in content delivery networks and international services. + * + * The resource is unavailable due to legal restrictions. The client should not retry the request as it will not be available. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc7725 | RFC 7725} + */ + "451"?: Response; + + //#endregion + + //#region 5xx — Server Error + + /** 500 Internal Server Error + * + * Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. + * + * The server encountered an internal error or exception that prevented it from processing the request successfully. + * + * Used for server-side errors, unhandled exceptions, database connection failures, or any unexpected server-side issue. Common in applications when there are bugs, configuration issues, or resource problems. + * + * The server encountered an internal error. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error | RFC 9110 §15.6.1} + */ + "500"?: Response; + + /** 501 Not Implemented + * + * Indicates that the server does not support the functionality required to fulfill the request. + * + * The server does not recognize the request method or lacks the ability to fulfill the request. + * + * Used when the server doesn't support the requested HTTP method, when functionality is not implemented, or when the server cannot handle the request. Common in API development when endpoints are not yet implemented. + * + * The server does not support the requested functionality. The client should check the API documentation for supported methods and features. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-501-not-implemented | RFC 9110 §15.6.2} + */ + "501"?: Response; + + /** 502 Bad Gateway + * + * Indicates that the server, while acting as a gateway or proxy, received an invalid response from an upstream server. + * + * The server acting as a gateway or proxy received an invalid response from the upstream server it was trying to access. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server returns an invalid response or is unreachable. Common in microservices architectures and distributed systems. + * + * The gateway received an invalid response from the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway | RFC 9110 §15.6.3} + */ + "502"?: Response; + + /** 503 Service Unavailable + * + * Indicates that the server is temporarily unable to handle the request due to maintenance or overload. + * + * The server is temporarily unavailable, typically due to maintenance, overload, or temporary resource constraints. + * + * Used during server maintenance, when the server is overloaded, when there are temporary resource issues, or when the service is temporarily down. Common in high-traffic scenarios and planned maintenance windows. + * + * The server is temporarily unavailable. The client should retry the request later, often with exponential backoff. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable | RFC 9110 §15.6.4} + */ + "503"?: Response; + + /** 504 Gateway Timeout + * + * Indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server. + * + * The gateway or proxy server timed out while waiting for a response from the upstream server. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server takes too long to respond. Common in microservices architectures where services have different response times. + * + * The gateway timed out waiting for the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-504-gateway-timeout | RFC 9110 §15.6.5} + */ + "504"?: Response; + + /** 505 HTTP Version Not Supported + * + * Indicates that the server does not support the HTTP protocol version used in the request. + * + * The server does not support the HTTP protocol version specified in the request. + * + * Used when the client uses an unsupported HTTP version, when the server only supports specific HTTP versions, or when there are protocol version mismatches. Common in legacy systems and protocol migration scenarios. + * + * The server does not support the HTTP version used in the request. The client should use a supported HTTP version. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-supporte | RFC 9110 §15.6.6} + */ + "505"?: Response; + + /** 506 Variant Also Negotiates + * + * Indicates that the server has an internal configuration error in which the chosen variant resource is configured to engage in transparent content negotiation. + * + * The server has a configuration error where the selected variant resource is configured to engage in transparent content negotiation, creating a negotiation loop. + * + * Used in content negotiation scenarios where there's a configuration error causing negotiation loops. Common in complex content delivery systems and advanced HTTP implementations. + * + * The server has a configuration error in content negotiation. The client should contact the server administrator. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2295 | RFC 2295} + */ + "506"?: Response; + + /** 507 Insufficient Storage + * + * Indicates that the server is unable to store the representation needed to complete the request. + * + * The server cannot store the representation required to complete the request, typically due to storage space limitations. + * + * Used in WebDAV environments when there's insufficient storage space, when the server cannot allocate storage for the request, or when storage quotas are exceeded. Common in file management systems and collaborative editing platforms. + * + * The server cannot store the required representation. The client should check storage availability and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "507"?: Response; + + /** 508 Loop Detected + * + * Indicates that the server detected an infinite loop while processing the request. + * + * The server detected an infinite loop in the request processing, typically in WebDAV operations. + * + * Used in WebDAV environments when there are infinite loops in request processing, when there are circular references in operations, or when the server detects recursive operations. Common in file management systems and collaborative editing scenarios. + * + * The server detected an infinite loop. The client should check the request for circular references and retry. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "508"?: Response; + + /** 510 Not Extended — OBSOLETED + * + * This status code is obsolete and should not be used in modern implementations. + * + * This status code was used for HTTP extensions but is now obsolete and should not be used. + * + * Not used in modern web applications. This code is obsolete and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2774 | RFC 2774 (Historic)} + * @see {@link https://datatracker.ietf.org/doc/status-change-http-experiments-to-historic/ | IETF: Status change of HTTP experiments to Historic} + */ + "510"?: Response; + + /** 511 Network Authentication Required + * + * Indicates that the client needs to authenticate to gain network access. + * + * The client must authenticate with the network before it can access the requested resource. + * + * Used in captive portal scenarios, public Wi-Fi networks, or when network-level authentication is required. Common in public networks, hotels, airports, and other locations where network access requires authentication. + * + * The client needs to authenticate with the network. The client should follow the authentication process provided by the network. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "511"?: Response; + + //#endregion + + /** default — The default response for all codes not covered individually. */ + default?: Response; +} diff --git a/2.0.0/tags.ts b/2.0/tags.ts similarity index 51% rename from 2.0.0/tags.ts rename to 2.0/tags.ts index 3eeb19d..576238f 100644 --- a/2.0.0/tags.ts +++ b/2.0/tags.ts @@ -1,15 +1,15 @@ -import type { Extension } from "./extensions" -import type { ExternalDocumentation } from "./external-documentation" +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; /** * ----- * Tag Object * ----- * - * A grouping tag for operations. Tags can be used for logical grouping of operations - * by resources or any other qualifier. The order of the tags can be used to reflect - * on their order by the parsing tools. Not all tags that are used by the Operation - * Object must be declared. The tags that are not declared may be organized randomly + * A grouping tag for operations. Tags can be used for logical grouping of operations + * by resources or any other qualifier. The order of the tags can be used to reflect + * on their order by the parsing tools. Not all tags that are used by the Operation + * Object must be declared. The tags that are not declared may be organized randomly * or based on the tools' logic. Each tag name in the list MUST be unique. * * Tags provide a way to organize and categorize API operations, making it easier @@ -24,9 +24,9 @@ import type { ExternalDocumentation } from "./external-documentation" * Fields * ----- * - * @key `name` - The name of the tag. This field is required and MUST be unique. - * @key `description` - A short description for the tag. GFM syntax can be used for rich text representation. - * @key `externalDocs` - Additional external documentation for this tag. + * @property `name` - The name of the tag. This field is required and MUST be unique. + * @property `description` - A short description for the tag. GFM syntax can be used for rich text representation. + * @property `externalDocs` - Additional external documentation for this tag. * * @note * All fields are optional except for `name`. The `name` field must be unique @@ -88,40 +88,46 @@ import type { ExternalDocumentation } from "./external-documentation" * ``` */ export interface Tag extends Extension { - /** - * The name of the tag. This field is required and MUST be unique. - * - * The tag name is used to reference this tag in Operation objects and - * must be unique within the entire specification. It should be descriptive - * and follow a consistent naming convention. - * - * @example "users" - * @example "pets" - * @example "authentication" - * @example "reports" - */ - name: string - - /** - * A short description for the tag. GFM syntax can be used for rich text representation. - * - * This description provides context about what operations belong to this tag - * and helps developers understand the purpose and scope of the tag. - * - * @example "User management operations" - * @example "Pet store operations including CRUD operations for pets" - * @example "Authentication and authorization operations" - */ - description?: string - - /** - * Additional external documentation for this tag. - * - * This allows for more detailed documentation about the tag and its - * associated operations to be provided via external resources. - * - * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } - * @example { description: "Pet management API documentation", url: "https://petstore.example.com/docs" } - */ - externalDocs?: ExternalDocumentation + /** + * The name of the tag. This field is required and MUST be unique. + * + * The tag name is used to reference this tag in Operation objects and + * must be unique within the entire specification. It should be descriptive + * and follow a consistent naming convention. + * + * @see {@link https://swagger.io/specification/v2/#tag-object | Swagger 2.0 Specification - name} + * + * @example "users" + * @example "pets" + * @example "authentication" + * @example "reports" + */ + name: string; + + /** + * A short description for the tag. GFM syntax can be used for rich text representation. + * + * This description provides context about what operations belong to this tag + * and helps developers understand the purpose and scope of the tag. + * + * @see {@link https://swagger.io/specification/v2/#tag-object | Swagger 2.0 Specification - description} + * + * @example "User management operations" + * @example "Pet store operations including CRUD operations for pets" + * @example "Authentication and authorization operations" + */ + description?: string; + + /** + * Additional external documentation for this tag. + * + * This allows for more detailed documentation about the tag and its + * associated operations to be provided via external resources. + * + * @see {@link https://swagger.io/specification/v2/#tag-object | Swagger 2.0 Specification - externalDocs} + * + * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } + * @example { description: "Pet management API documentation", url: "https://petstore.example.com/docs" } + */ + externalDocs?: ExternalDocumentation; } diff --git a/2.0/xml.ts b/2.0/xml.ts new file mode 100644 index 0000000..c8fa660 --- /dev/null +++ b/2.0/xml.ts @@ -0,0 +1,142 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * XML Object + * ----- + * + * A metadata object that allows for more fine-tuned XML model definitions. + * When using arrays, XML element names are not inferred (for singular/plural forms) + * and the name property should be used to add that information. + * + * The XML Object provides additional metadata to describe the XML representation + * format of schema properties. It allows for precise control over how JSON + * schema definitions are translated to XML, including element naming, namespaces, + * attributes, and array wrapping. + * + * | Version | Reference | + * |---|-----| + * | 2.0 | {@link https://swagger.io/specification/v2/#xml-object | Swagger 2.0 XML Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Replaces the name of the element/attribute used for the described schema property. + * @property `namespace` - The URL of the namespace definition. Value SHOULD be in the form of a URL. + * @property `prefix` - The prefix to be used for the name. + * @property `attribute` - Declares whether the property definition translates to an attribute instead of an element. Default value is false. + * @property `wrapped` - MAY be used only for an array definition. Signifies whether the array is wrapped. Default value is false. + * + * @note + * All fields are optional. The `wrapped` property only takes effect when defined + * alongside `type` being `array` (outside the items). When `wrapped` is true, + * arrays are wrapped in a container element. + * + * ----- + * Examples + * ----- + * + * @example (basic XML element): + * ```ts + * const basicXml: XMLObject = { + * name: "animal" + * }; + * ``` + * + * @example (XML attribute): + * ```ts + * const attributeXml: XMLObject = { + * name: "id", + * attribute: true + * }; + * ``` + * + * @example (namespaced XML): + * ```ts + * const namespacedXml: XMLObject = { + * name: "name", + * namespace: "http://swagger.io/schema/sample", + * prefix: "sample" + * }; + * ``` + * + * @example (wrapped array): + * ```ts + * const wrappedArrayXml: XMLObject = { + * name: "animals", + * wrapped: true + * }; + * ``` + * + * @example (array items with custom name): + * ```ts + * const arrayItemsXml: XMLObject = { + * name: "animal" + * }; + * ``` + * + * @example (complete XML definition): + * ```ts + * const completeXml: XMLObject = { + * name: "person", + * namespace: "http://example.com/schema", + * prefix: "ex", + * attribute: false, + * wrapped: false + * }; + * ``` + */ +export interface XMLObject extends Extension { + /** + * Replaces the name of the element/attribute used for the described schema property. + * When defined within the Items Object, it will affect the name of the individual + * XML elements within the list. When defined alongside type being array (outside + * the items), it will affect the wrapping element and only if wrapped is true. + * + * @example "animal" + * @example "item" + * @example "person" + */ + name?: string; + + /** + * The URL of the namespace definition. Value SHOULD be in the form of a URL. + * + * @example "http://example.com/schema/sample" + * @example "http://www.w3.org/2001/XMLSchema" + * @example "http://swagger.io/schema/sample" + */ + namespace?: string; + + /** + * The prefix to be used for the name. + * + * @example "sample" + * @example "xs" + * @example "ex" + */ + prefix?: string; + + /** + * Declares whether the property definition translates to an attribute instead of an element. + * Default value is false. + * + * @default false + * @example true + * @example false + */ + attribute?: boolean; + + /** + * MAY be used only for an array definition. Signifies whether the array is wrapped + * (for example, ) or unwrapped (). + * Default value is false. The definition takes effect only when defined alongside + * type being array (outside the items). + * + * @default false + * @example true + * @example false + */ + wrapped?: boolean; +} diff --git a/3.0.x/components.ts b/3.0.x/components.ts deleted file mode 100644 index 040322c..0000000 --- a/3.0.x/components.ts +++ /dev/null @@ -1,123 +0,0 @@ -import type { Schema } from "./schema" -import type { Reference } from "./references" -import type { Extension } from "./extensions" - -/** - * ----- - * Components Object - * ----- - * - * Holds a set of reusable objects for different aspects of the OAS. All objects defined - * within the components object will have no effect on the API unless they are explicitly - * referenced from properties outside the components object. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object} | - * - * ----- - * Fields - * ----- - * - * @key `schemas` - An object to hold reusable Schema Objects - * @key `responses` - An object to hold reusable Response Objects - * @key `parameters` - An object to hold reusable Parameter Objects - * @key `examples` - An object to hold reusable Example Objects - * @key `requestBodies` - An object to hold reusable Request Body Objects - * @key `headers` - An object to hold reusable Header Objects - * @key `securitySchemes` - An object to hold reusable Security Scheme Objects - * @key `links` - An object to hold reusable Link Objects - * @key `callbacks` - An object to hold reusable Callback Objects - * @key `x-${string}` - Specification Extensions - * - * @note - * All objects defined within the components object will have no effect on the API unless - * they are explicitly referenced from properties outside the components object. - * - * ----- - * Examples - * ----- - * - * @example (basic components): - * ```ts - * const components: Components = { - * schemas: { - * User: { - * type: "object", - * properties: { - * id: { type: "integer" }, - * name: { type: "string" } - * } - * } - * } - * }; - * ``` - */ -export interface Components extends Extension { - /** - * An object to hold reusable Schema Objects. - * - * @example { "User": { type: "object", properties: { id: { type: "integer" } } } } - */ - schemas?: Record - - /** - * An object to hold reusable Response Objects. - * - * @example { "NotFound": { description: "Resource not found" } } - */ - responses?: Record - - /** - * An object to hold reusable Parameter Objects. - * - * @example { "LimitParam": { name: "limit", in: "query", schema: { type: "integer" } } } - */ - parameters?: Record - - /** - * An object to hold reusable Example Objects. - * - * @example { "UserExample": { summary: "A user example", value: { id: 1, name: "John" } } } - */ - examples?: Record - - /** - * An object to hold reusable Request Body Objects. - * - * @example { "UserRequest": { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } } - */ - requestBodies?: Record - - /** - * An object to hold reusable Header Objects. - * - * @example { "RateLimit": { description: "Rate limit header", schema: { type: "integer" } } } - */ - headers?: Record - - /** - * An object to hold reusable Security Scheme Objects. - * - * @example { "ApiKeyAuth": { type: "apiKey", in: "header", name: "X-API-Key" } } - */ - securitySchemes?: Record - - /** - * An object to hold reusable Link Objects. - * - * @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } } - */ - links?: Record - - /** - * An object to hold reusable Callback Objects. - * - * @example { "MyCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { $ref: "#/components/requestBodies/SomeRequestBody" } } } } } - */ - callbacks?: Record -} diff --git a/3.0.x/data-types/array.ts b/3.0.x/data-types/array.ts deleted file mode 100644 index 7e0cea2..0000000 --- a/3.0.x/data-types/array.ts +++ /dev/null @@ -1,206 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Array Schema - * ----- - * - * A schema for array data types with array-specific validation constraints. - * Only valid with `type: "array"` and includes array properties like - * `items`, `maxItems`, `minItems`, and `uniqueItems`. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "array" - * @key `items` - Schema for the items in the array - * @key `maxItems` - Maximum number of items in the array - * @key `minItems` - Minimum number of items in the array - * @key `uniqueItems` - Whether all items must be unique - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid array values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `x-${string}` - Specification Extensions - * - * @note - * Array-specific constraints (`items`, `maxItems`, `minItems`, `uniqueItems`) are only - * valid with `type: "array"`. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (basic array): - * ```ts - * const arraySchema: ArraySchema = { - * type: "array", - * items: { type: "string" }, - * description: "Array of strings" - * }; - * ``` - * - * @example (array with validation): - * ```ts - * const tagsSchema: ArraySchema = { - * type: "array", - * items: { type: "string" }, - * minItems: 1, - * maxItems: 10, - * uniqueItems: true, - * description: "Array of unique tags" - * }; - * ``` - * - * @example (array of objects): - * ```ts - * const usersSchema: ArraySchema = { - * type: "array", - * items: { $ref: "#/components/schemas/User" }, - * description: "Array of user objects" - * }; - * ``` - * - * @example (array with enum): - * ```ts - * const statusesSchema: ArraySchema = { - * type: "array", - * items: { type: "string", enum: ["active", "inactive"] }, - * description: "Array of status values" - * }; - * ``` - */ -export interface ArraySchema extends Extension { - /** - * The type of the schema. Must be "array" for array schemas. - * - * @example "array" - */ - type: "array" - - /** - * A short title for the schema. - * - * @example "Tags" - * @example "User List" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "Array of tag strings" - * @example "List of user objects" - */ - description?: string - - /** - * The default value for the schema. - * - * @example ["tag1", "tag2"] - * @example [] - */ - default?: any[] - - /** - * Example value for the schema. - * - * @example ["example1", "example2"] - * @example [1, 2, 3] - */ - example?: any[] - - /** - * Enumeration of valid array values. - * - * @example [["a", "b"], ["c", "d"]] - * @example [[1, 2], [3, 4]] - */ - enum?: any[][] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "tags", wrapped: true } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this field", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - // Array-specific validation constraints - /** - * Schema for the items in the array. This field is required for array schemas. - * - * @example { type: "string" } - * @example { $ref: "#/components/schemas/User" } - */ - items?: any // Will be properly typed as Schema | Reference when we set up the circular reference - - /** - * Maximum number of items in the array. The value MUST be a non-negative integer. - * - * @example 10 - * @example 100 - */ - maxItems?: number - - /** - * Minimum number of items in the array. The value MUST be a non-negative integer. - * - * @example 1 - * @example 0 - */ - minItems?: number - - /** - * Whether all items in the array must be unique. Default value is false. - * - * @default false - * @example true - */ - uniqueItems?: boolean -} diff --git a/3.0.x/data-types/boolean.ts b/3.0.x/data-types/boolean.ts deleted file mode 100644 index 15c2697..0000000 --- a/3.0.x/data-types/boolean.ts +++ /dev/null @@ -1,165 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Boolean Schema - * ----- - * - * A schema for boolean data types (true/false values) with basic validation. - * Only valid with `type: "boolean"` and includes common metadata properties - * but no boolean-specific validation constraints. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "boolean" - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid boolean values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `x-${string}` - Specification Extensions - * - * @note - * Boolean schemas have no type-specific validation constraints beyond - * the basic metadata properties. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (basic boolean): - * ```ts - * const booleanSchema: BooleanSchema = { - * type: "boolean", - * description: "A true/false value" - * }; - * ``` - * - * @example (boolean with default): - * ```ts - * const enabledSchema: BooleanSchema = { - * type: "boolean", - * default: false, - * description: "Whether the feature is enabled" - * }; - * ``` - * - * @example (boolean with enum): - * ```ts - * const statusSchema: BooleanSchema = { - * type: "boolean", - * enum: [true, false], - * default: false, - * description: "Active status" - * }; - * ``` - * - * @example (read-only boolean): - * ```ts - * const computedSchema: BooleanSchema = { - * type: "boolean", - * readOnly: true, - * description: "Computed value that cannot be set directly" - * }; - * ``` - */ -export interface BooleanSchema extends Extension { - /** - * The type of the schema. Must be "boolean" for boolean schemas. - * - * @example "boolean" - */ - type: "boolean" - - /** - * A short title for the schema. - * - * @example "Is Active" - * @example "Enabled" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "Whether the user is active" - * @example "Feature enabled status" - */ - description?: string - - /** - * The default value for the schema. - * - * @example true - * @example false - */ - default?: boolean - - /** - * Example value for the schema. - * - * @example true - * @example false - */ - example?: boolean - - /** - * Enumeration of valid boolean values. - * - * @example [true, false] - */ - enum?: boolean[] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "isActive", attribute: true } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this field", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean -} diff --git a/3.0.x/data-types/composition.ts b/3.0.x/data-types/composition.ts deleted file mode 100644 index 802918a..0000000 --- a/3.0.x/data-types/composition.ts +++ /dev/null @@ -1,207 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Composition Schema - * ----- - * - * A schema that uses composition keywords (allOf, anyOf, oneOf, not) for schema - * composition and logical operations. These keywords are mutually exclusive with - * `$ref` but can appear with any validation keywords. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `allOf` - Array of schemas that must all be valid - * @key `anyOf` - Array of schemas where at least one must be valid - * @key `oneOf` - Array of schemas where exactly one must be valid - * @key `not` - Schema that must not be valid - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `discriminator` - Discriminator for polymorphism - * @key `x-${string}` - Specification Extensions - * - * @note - * Composition keywords are mutually exclusive with `$ref` but can appear with - * any validation keywords. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (allOf composition): - * ```ts - * const composedSchema: CompositionSchema = { - * allOf: [ - * { $ref: "#/components/schemas/BaseUser" }, - * { type: "object", required: ["id"] } - * ], - * description: "User with base properties plus required id" - * }; - * ``` - * - * @example (anyOf composition): - * ```ts - * const flexibleSchema: CompositionSchema = { - * anyOf: [ - * { type: "string" }, - * { type: "integer" } - * ], - * description: "String or integer value" - * }; - * ``` - * - * @example (oneOf composition): - * ```ts - * const choiceSchema: CompositionSchema = { - * oneOf: [ - * { $ref: "#/components/schemas/Dog" }, - * { $ref: "#/components/schemas/Cat" } - * ], - * discriminator: "petType", - * description: "Either a dog or cat" - * }; - * ``` - * - * @example (not composition): - * ```ts - * const exclusionSchema: CompositionSchema = { - * not: { type: "null" }, - * description: "Any value except null" - * }; - * ``` - */ -export interface CompositionSchema extends Extension { - /** - * A short title for the schema. - * - * @example "Composed User" - * @example "Flexible Value" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "Schema composed from multiple base schemas" - * @example "Value that can be string or number" - */ - description?: string - - /** - * The default value for the schema. - * - * @example "default value" - * @example { name: "default" } - */ - default?: any - - /** - * Example value for the schema. - * - * @example "example value" - * @example { name: "example" } - */ - example?: any - - /** - * Enumeration of valid values. - * - * @example ["value1", "value2"] - * @example [1, 2, 3] - */ - enum?: any[] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "composed", wrapped: true } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this schema", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - /** - * Discriminator for polymorphism. The property name used to differentiate between schemas. - * - * @example "petType" - * @example "type" - */ - discriminator?: any // Will be properly typed when we import Discriminator type - - // Composition keywords (mutually exclusive) - /** - * Array of schemas that must all be valid for the instance to be valid. - * - * @example [{ $ref: "#/components/schemas/Base" }, { type: "object", required: ["id"] }] - */ - allOf?: any[] // Will be properly typed as (Schema | Reference)[] when we set up the circular reference - - /** - * Array of schemas where at least one must be valid for the instance to be valid. - * - * @example [{ type: "string" }, { type: "integer" }] - */ - anyOf?: any[] // Will be properly typed as (Schema | Reference)[] when we set up the circular reference - - /** - * Array of schemas where exactly one must be valid for the instance to be valid. - * - * @example [{ $ref: "#/components/schemas/Dog" }, { $ref: "#/components/schemas/Cat" }] - */ - oneOf?: any[] // Will be properly typed as (Schema | Reference)[] when we set up the circular reference - - /** - * Schema that must not be valid for the instance to be valid. - * - * @example { type: "null" } - * @example { type: "string", maxLength: 0 } - */ - not?: any // Will be properly typed as Schema | Reference when we set up the circular reference -} diff --git a/3.0.x/data-types/index.ts b/3.0.x/data-types/index.ts deleted file mode 100644 index 29ddc03..0000000 --- a/3.0.x/data-types/index.ts +++ /dev/null @@ -1,9 +0,0 @@ -// Individual schema types -export type { ReferenceSchema } from "./reference" -export type { StringSchema } from "./string" -export type { NumberSchema } from "./number" -export type { IntegerSchema } from "./integer" -export type { BooleanSchema } from "./boolean" -export type { ArraySchema } from "./array" -export type { ObjectSchema } from "./object" -export type { CompositionSchema } from "./composition" diff --git a/3.0.x/data-types/integer.ts b/3.0.x/data-types/integer.ts deleted file mode 100644 index e04fda6..0000000 --- a/3.0.x/data-types/integer.ts +++ /dev/null @@ -1,223 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Integer Schema - * ----- - * - * A schema for integer data types (whole numbers) with integer-specific - * validation constraints. Only valid with `type: "integer"` and includes - * numeric properties like `multipleOf`, `maximum`, `minimum`, etc. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "integer" - * @key `format` - The extending format for the integer type - * @key `multipleOf` - Number must be a multiple of this value - * @key `maximum` - Maximum value (inclusive) - * @key `exclusiveMaximum` - Maximum value (exclusive) - * @key `minimum` - Minimum value (inclusive) - * @key `exclusiveMinimum` - Minimum value (exclusive) - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid integer values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `x-${string}` - Specification Extensions - * - * @note - * Integer-specific constraints (`multipleOf`, `maximum`, `minimum`, etc.) are only - * valid with `type: "integer"`. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (basic integer): - * ```ts - * const integerSchema: IntegerSchema = { - * type: "integer", - * description: "A whole number" - * }; - * ``` - * - * @example (integer with format): - * ```ts - * const int32Schema: IntegerSchema = { - * type: "integer", - * format: "int32", - * description: "32-bit signed integer" - * }; - * ``` - * - * @example (integer with validation): - * ```ts - * const ageSchema: IntegerSchema = { - * type: "integer", - * minimum: 0, - * maximum: 150, - * description: "Person's age in years" - * }; - * ``` - * - * @example (integer with enum): - * ```ts - * const statusCodeSchema: IntegerSchema = { - * type: "integer", - * enum: [200, 201, 400, 401, 404, 500], - * description: "HTTP status code" - * }; - * ``` - */ -export interface IntegerSchema extends Extension { - /** - * The type of the schema. Must be "integer" for integer schemas. - * - * @example "integer" - */ - type: "integer" - - /** - * The extending format for the integer type. See OpenAPI 3.0.x Data Type Formats for details. - * - * @example "int32" - * @example "int64" - */ - format?: string - - /** - * A short title for the schema. - * - * @example "User ID" - * @example "Age" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "The user's unique identifier" - * @example "Age in years" - */ - description?: string - - /** - * The default value for the schema. - * - * @example 0 - * @example 1 - */ - default?: number - - /** - * Example value for the schema. - * - * @example 42 - * @example 100 - */ - example?: number - - /** - * Enumeration of valid integer values. - * - * @example [1, 2, 3, 4, 5] - * @example [0, 1, 2] - */ - enum?: number[] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "userId", attribute: true } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this field", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - // Integer-specific validation constraints - /** - * A number is valid against "multipleOf" if the result of the division - * of the instance by this keyword's value is an integer. - * - * @example 1 - * @example 2 - * @example 5 - */ - multipleOf?: number - - /** - * A number is valid against "maximum" if it is less than or equal to this value. - * - * @example 100 - * @example 2147483647 - */ - maximum?: number - - /** - * A number is valid against "exclusiveMaximum" if it is strictly less than this value. - * - * @example 100 - * @example 1000 - */ - exclusiveMaximum?: number - - /** - * A number is valid against "minimum" if it is greater than or equal to this value. - * - * @example 0 - * @example 1 - */ - minimum?: number - - /** - * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. - * - * @example 0 - * @example -1 - */ - exclusiveMinimum?: number -} diff --git a/3.0.x/data-types/number.ts b/3.0.x/data-types/number.ts deleted file mode 100644 index d006aba..0000000 --- a/3.0.x/data-types/number.ts +++ /dev/null @@ -1,225 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Number Schema - * ----- - * - * A schema for numeric data types (floating-point numbers) with numeric-specific - * validation constraints. Only valid with `type: "number"` and includes numeric - * properties like `multipleOf`, `maximum`, `minimum`, etc. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "number" - * @key `format` - The extending format for the number type - * @key `multipleOf` - Number must be a multiple of this value - * @key `maximum` - Maximum value (inclusive) - * @key `exclusiveMaximum` - Maximum value (exclusive) - * @key `minimum` - Minimum value (inclusive) - * @key `exclusiveMinimum` - Minimum value (exclusive) - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid number values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `x-${string}` - Specification Extensions - * - * @note - * Numeric constraints (`multipleOf`, `maximum`, `minimum`, etc.) are only - * valid with `type: "number"` or `type: "integer"`. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (basic number): - * ```ts - * const numberSchema: NumberSchema = { - * type: "number", - * description: "A floating-point number" - * }; - * ``` - * - * @example (number with format): - * ```ts - * const floatSchema: NumberSchema = { - * type: "number", - * format: "float", - * description: "Single precision floating-point number" - * }; - * ``` - * - * @example (number with validation): - * ```ts - * const priceSchema: NumberSchema = { - * type: "number", - * minimum: 0, - * maximum: 999.99, - * multipleOf: 0.01, - * description: "Price in dollars with cent precision" - * }; - * ``` - * - * @example (number with enum): - * ```ts - * const ratingSchema: NumberSchema = { - * type: "number", - * enum: [1.0, 2.0, 3.0, 4.0, 5.0], - * default: 3.0, - * description: "Product rating from 1 to 5" - * }; - * ``` - */ -export interface NumberSchema extends Extension { - /** - * The type of the schema. Must be "number" for number schemas. - * - * @example "number" - */ - type: "number" - - /** - * The extending format for the number type. See OpenAPI 3.0.x Data Type Formats for details. - * - * @example "float" - * @example "double" - */ - format?: string - - /** - * A short title for the schema. - * - * @example "Price" - * @example "Temperature" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "The price in dollars" - * @example "Temperature in Celsius" - */ - description?: string - - /** - * The default value for the schema. - * - * @example 0 - * @example 25.5 - */ - default?: number - - /** - * Example value for the schema. - * - * @example 19.99 - * @example 98.6 - */ - example?: number - - /** - * Enumeration of valid number values. - * - * @example [1.0, 2.0, 3.0, 4.0, 5.0] - * @example [0.0, 0.5, 1.0] - */ - enum?: number[] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "price", attribute: true } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this field", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - // Number-specific validation constraints - /** - * A number is valid against "multipleOf" if the result of the division - * of the instance by this keyword's value is an integer. - * - * @example 0.01 - * @example 0.1 - * @example 2 - */ - multipleOf?: number - - /** - * A number is valid against "maximum" if it is less than or equal to this value. - * - * @example 100 - * @example 999.99 - */ - maximum?: number - - /** - * A number is valid against "exclusiveMaximum" if it is strictly less than this value. - * - * @example 100 - * @example 1000 - */ - exclusiveMaximum?: number - - /** - * A number is valid against "minimum" if it is greater than or equal to this value. - * - * @example 0 - * @example -273.15 - */ - minimum?: number - - /** - * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. - * - * @example 0 - * @example -100 - */ - exclusiveMinimum?: number -} diff --git a/3.0.x/data-types/object.ts b/3.0.x/data-types/object.ts deleted file mode 100644 index 480eef2..0000000 --- a/3.0.x/data-types/object.ts +++ /dev/null @@ -1,256 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Object Schema - * ----- - * - * A schema for object data types with object-specific validation constraints. - * Only valid with `type: "object"` and includes object properties like - * `properties`, `required`, `additionalProperties`, etc. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "object" - * @key `properties` - Properties of the object - * @key `required` - Required property names - * @key `additionalProperties` - Additional properties schema - * @key `patternProperties` - Pattern-based properties - * @key `propertyNames` - Schema for property names - * @key `maxProperties` - Maximum number of properties - * @key `minProperties` - Minimum number of properties - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid object values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `discriminator` - Discriminator for polymorphism - * @key `x-${string}` - Specification Extensions - * - * @note - * Object-specific constraints (`properties`, `required`, `additionalProperties`, etc.) are only - * valid with `type: "object"`. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (basic object): - * ```ts - * const objectSchema: ObjectSchema = { - * type: "object", - * properties: { - * name: { type: "string" }, - * age: { type: "integer" } - * }, - * description: "A person object" - * }; - * ``` - * - * @example (object with required properties): - * ```ts - * const userSchema: ObjectSchema = { - * type: "object", - * properties: { - * id: { type: "integer" }, - * name: { type: "string" }, - * email: { type: "string", format: "email" } - * }, - * required: ["id", "name", "email"], - * description: "User object with required fields" - * }; - * ``` - * - * @example (object with additional properties): - * ```ts - * const flexibleSchema: ObjectSchema = { - * type: "object", - * properties: { - * id: { type: "integer" } - * }, - * additionalProperties: { type: "string" }, - * description: "Object allowing additional string properties" - * }; - * ``` - * - * @example (object with discriminator): - * ```ts - * const petSchema: ObjectSchema = { - * type: "object", - * discriminator: "petType", - * properties: { - * name: { type: "string" }, - * petType: { type: "string" } - * }, - * required: ["name", "petType"], - * description: "Base pet object with discriminator" - * }; - * ``` - */ -export interface ObjectSchema extends Extension { - /** - * The type of the schema. Must be "object" for object schemas. - * - * @example "object" - */ - type: "object" - - /** - * A short title for the schema. - * - * @example "User" - * @example "Product" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "A user object containing basic information" - * @example "Product information with pricing" - */ - description?: string - - /** - * The default value for the schema. - * - * @example { name: "John", age: 30 } - * @example {} - */ - default?: Record - - /** - * Example value for the schema. - * - * @example { name: "Jane", age: 25 } - * @example { id: 1, title: "Sample" } - */ - example?: Record - - /** - * Enumeration of valid object values. - * - * @example [{ name: "John" }, { name: "Jane" }] - * @example [{ status: "active" }, { status: "inactive" }] - */ - enum?: Record[] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "user", wrapped: false } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this object", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - /** - * Discriminator for polymorphism. The property name used to differentiate between schemas. - * - * @example "petType" - * @example "type" - */ - discriminator?: any // Will be properly typed when we import Discriminator type - - // Object-specific validation constraints - /** - * Properties of the object. Each property name maps to a schema definition. - * - * @example { name: { type: "string" }, age: { type: "integer" } } - * @example { id: { $ref: "#/components/schemas/Id" } } - */ - properties?: Record // Will be properly typed as Schema | Reference when we set up the circular reference - - /** - * Array of property names that are required. Properties not listed here are optional. - * - * @example ["id", "name"] - * @example ["email"] - */ - required?: string[] - - /** - * Schema for additional properties not defined in the properties object. - * Can be a boolean or a schema. - * - * @example true - * @example false - * @example { type: "string" } - */ - additionalProperties?: boolean | any // Will be properly typed as Schema | Reference when we set up the circular reference - - /** - * Pattern-based properties using regular expressions as keys. - * - * @example { "^S_": { type: "string" } } - * @example { "^[0-9]+$": { type: "integer" } } - */ - patternProperties?: Record // Will be properly typed as Schema | Reference when we set up the circular reference - - /** - * Schema for property names. If present, property names must conform to this schema. - * - * @example { type: "string", pattern: "^[a-zA-Z][a-zA-Z0-9]*$" } - */ - propertyNames?: any // Will be properly typed as Schema | Reference when we set up the circular reference - - /** - * Maximum number of properties in the object. The value MUST be a non-negative integer. - * - * @example 10 - * @example 50 - */ - maxProperties?: number - - /** - * Minimum number of properties in the object. The value MUST be a non-negative integer. - * - * @example 1 - * @example 2 - */ - minProperties?: number -} diff --git a/3.0.x/data-types/string.ts b/3.0.x/data-types/string.ts deleted file mode 100644 index 1507972..0000000 --- a/3.0.x/data-types/string.ts +++ /dev/null @@ -1,207 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * String Schema - * ----- - * - * A schema for string data types with string-specific validation constraints. - * Only valid with `type: "string"` and includes string-specific properties - * like `maxLength`, `minLength`, and `pattern`. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Must be "string" - * @key `format` - The extending format for the string type - * @key `maxLength` - Maximum length of the string - * @key `minLength` - Minimum length of the string - * @key `pattern` - Regular expression pattern the string must match - * @key `title` - A short title for the schema - * @key `description` - A short description of the schema - * @key `default` - Default value for the schema - * @key `example` - Example value for the schema - * @key `enum` - Enumeration of valid string values - * @key `readOnly` - Whether the property is read-only - * @key `writeOnly` - Whether the property is write-only - * @key `xml` - XML representation metadata - * @key `externalDocs` - Additional external documentation - * @key `deprecated` - Whether the schema is deprecated - * @key `x-${string}` - Specification Extensions - * - * @note - * String-specific constraints (`maxLength`, `minLength`, `pattern`) are only - * valid with `type: "string"`. This is enforced by the type system. - * - * ----- - * Examples - * ----- - * - * @example (basic string): - * ```ts - * const stringSchema: StringSchema = { - * type: "string", - * description: "A simple string field" - * }; - * ``` - * - * @example (string with format): - * ```ts - * const emailSchema: StringSchema = { - * type: "string", - * format: "email", - * description: "Email address" - * }; - * ``` - * - * @example (string with validation): - * ```ts - * const passwordSchema: StringSchema = { - * type: "string", - * minLength: 8, - * maxLength: 128, - * pattern: "^[a-zA-Z0-9!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>\\/?]+$", - * description: "Password with length and character requirements" - * }; - * ``` - * - * @example (string with enum): - * ```ts - * const statusSchema: StringSchema = { - * type: "string", - * enum: ["active", "inactive", "pending"], - * default: "pending", - * description: "User status" - * }; - * ``` - */ -export interface StringSchema extends Extension { - /** - * The type of the schema. Must be "string" for string schemas. - * - * @example "string" - */ - type: "string" - - /** - * The extending format for the string type. See OpenAPI 3.0.x Data Type Formats for details. - * - * @example "email" - * @example "date" - * @example "uuid" - * @example "uri" - */ - format?: string - - /** - * A short title for the schema. - * - * @example "User Name" - * @example "Email Address" - */ - title?: string - - /** - * A short description of the schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "The user's full name" - * @example "Email address in RFC 5322 format" - */ - description?: string - - /** - * The default value for the schema. - * - * @example "John Doe" - * @example "user@example.com" - */ - default?: string - - /** - * Example value for the schema. - * - * @example "Jane Smith" - * @example "admin@example.com" - */ - example?: string - - /** - * Enumeration of valid string values. - * - * @example ["active", "inactive", "pending"] - * @example ["red", "green", "blue"] - */ - enum?: string[] - - /** - * Whether the property is read-only. Default value is false. - * - * @default false - * @example true - */ - readOnly?: boolean - - /** - * Whether the property is write-only. Default value is false. - * - * @default false - * @example true - */ - writeOnly?: boolean - - /** - * XML representation metadata for the schema. - * - * @example { name: "userName", attribute: false } - */ - xml?: any // Will be properly typed when we import XML type - - /** - * Additional external documentation for the schema. - * - * @example { description: "Find out more about this field", url: "https://example.com/docs" } - */ - externalDocs?: any // Will be properly typed when we import ExternalDocumentation type - - /** - * Whether the schema is deprecated. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - // String-specific validation constraints - /** - * Maximum length of the string. The value MUST be a non-negative integer. - * - * @example 100 - * @example 255 - */ - maxLength?: number - - /** - * Minimum length of the string. The value MUST be a non-negative integer. - * - * @example 1 - * @example 8 - */ - minLength?: number - - /** - * Regular expression pattern the string must match. The pattern MUST be a valid regular expression. - * - * @example "^[a-zA-Z0-9]+$" - * @example "^\\d{4}-\\d{2}-\\d{2}$" - */ - pattern?: string -} diff --git a/3.0.x/externalDocs.ts b/3.0.x/externalDocs.ts deleted file mode 100644 index e486b4b..0000000 --- a/3.0.x/externalDocs.ts +++ /dev/null @@ -1,57 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * External Documentation Object - * ----- - * - * Allows referencing an external resource for extended documentation. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation} | - * - * ----- - * Fields - * ----- - * - * @key `description` - Optional A short description of the target documentation - * @key `url` - Required The URL for the target documentation - * @key `x-${string}` - Specification Extensions - * - * @note - * The `url` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple external docs): - * ```ts - * const externalDocs: ExternalDocumentation = { - * description: "Find more info here", - * url: "https://example.com/docs" - * }; - * ``` - */ -export interface ExternalDocumentation extends Extension { - /** - * A short description of the target documentation. CommonMark syntax MAY be used for rich text representation. - * - * @example "Find more info here" - * @example "Additional documentation for this API" - */ - description?: string - - /** - * The URL for the target documentation. MUST be in the format of a URL. - * - * @example "https://example.com/docs" - * @example "https://api.example.com/documentation" - */ - url: string -} diff --git a/3.0.x/index.ts b/3.0.x/index.ts deleted file mode 100644 index 047750c..0000000 --- a/3.0.x/index.ts +++ /dev/null @@ -1,65 +0,0 @@ -// Centralized exports for OpenAPI 3.0 types -// This file serves as the main entry point for all OpenAPI 3.0 type definitions - -// Export the main specification type -export type { Specification } from "./spec" - -// Re-export all types for convenience -export type { - // Core types - Extension -} from "./extensions" - -export type { - Contact, - // Info types - Info, License -} from "./info" - -export type { - // Server types - Server, - ServerVariable -} from "./servers" - -export type { - Callback, Encoding, Example, Header, Link, MediaType, Operation, - Parameter, - // Path types - PathItemObject, RequestBody, Response -} from "./paths" - -export type { - // Components types - Components -} from "./components" - -export type { - Discriminator, - // Schema types - Schema -} from "./schema" - -export type { - // XML types - XML -} from "./xml" - -export type { - OAuthFlow, OAuthFlows, SecurityRequirement, - // Security types - SecurityScheme -} from "./security" - -export type { - // Utility types - Tag -} from "./tags" - -export type { - ExternalDocumentation, -} from "./external-documentation" - -export type { - Reference, -} from "./references" diff --git a/3.0.x/info.ts b/3.0.x/info.ts deleted file mode 100644 index aa170e0..0000000 --- a/3.0.x/info.ts +++ /dev/null @@ -1,295 +0,0 @@ -import type { Extension } from "./extensions" -import type { LicenseName, LicenseURL } from "../License" -import type { ExternalDocumentation } from "./externalDocs" - -/** - * ----- - * Info Object - * ----- - * - * The object provides metadata about the API. - * The metadata MAY be used by the clients if needed, and MAY be presented in - * editing or documentation generation tools for convenience. - * - * The Info Object provides metadata about the API. This metadata can be used by - * clients if needed, and can be presented in the OpenAPI-UI for convenience. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info} | - * - * ----- - * Fields - * ----- - * - * @key `title` - Required The title of the application - * @key `description` - Optional A short description of the application - * @key `termsOfService` - Optional A URL to the Terms of Service for the API - * @key `contact` - Optional The contact information for the exposed API - * @key `license` - Optional The license information for the exposed API - * @key `version` - Required The version of the OpenAPI document - * @key `x-${string}` - Specification Extensions - * - * @note - * The `title` and `version` fields are required. In OpenAPI 3.0.1+, the `description` - * field was clarified to support CommonMark syntax for rich text representation. - * The `termsOfService` field must be a valid URL format. - * - * ----- - * Examples - * ----- - * - * @example (minimal info): - * ```ts - * const info: Info = { - * title: "Sample Pet Store App", - * version: "1.0.1" - * }; - * ``` - * - * @example (full info object): - * ```ts - * const info: Info = { - * title: "Sample Pet Store App", - * description: "This is a sample server for a pet store.", - * termsOfService: "http://example.com/terms/", - * contact: { - * name: "API Support", - * url: "http://www.example.com/support", - * email: "support@example.com" - * }, - * license: { - * name: "Apache 2.0", - * url: "http://www.apache.org/licenses/LICENSE-2.0.html" - * }, - * version: "1.0.1" - * }; - * ``` - */ -export interface Info extends Extension { - /** - * The title of the application. This field is required. - * - * @example "Sample Pet Store App" - * @example "My API" - */ - title: string - - /** - * A short description of the application. CommonMark syntax MAY be used for rich text representation. - * - * @example "This is a sample server for a pet store." - * @example "A comprehensive API for managing user data" - */ - description?: string - - /** - * A URL to the Terms of Service for the API. MUST be in the format of a URL. - * - * @example "http://example.com/terms/" - * @example "https://example.com/terms" - */ - termsOfService?: string - - /** - * The contact information for the exposed API. - * - * @example { name: "API Support", email: "support@example.com" } - */ - contact?: Contact - - /** - * The license information for the exposed API. - * - * @example { name: "Apache 2.0", url: "http://www.apache.org/licenses/LICENSE-2.0.html" } - */ - license?: License - - /** - * The version of the OpenAPI document (which is distinct from the OpenAPI Specification version - * or the API implementation version). This field is required. - * - * @example "1.0.1" - * @example "2.0.0" - */ - version: string -} - -/** - * ----- - * Contact Object - * ----- - * - * Contact information for the exposed API. - * - * The Contact Object provides contact information for the exposed API. It can - * include the name, URL, and email address of the contact person or organization. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Optional The identifying name of the contact person/organization - * @key `url` - Optional A URL pointing to the contact information - * @key `email` - Optional The email address of the contact person/organization - * @key `x-${string}` - Specification Extensions - * - * @note - * All fields are optional. In OpenAPI 3.0.1+, the `url` field was clarified to - * must be in the format of a URL, and the `email` field must be in the format - * of an email address. - * - * ----- - * Examples - * ----- - * - * @example (full contact object): - * ```ts - * const contact: Contact = { - * name: "API Support", - * url: "http://www.example.com/support", - * email: "support@example.com" - * }; - * ``` - * - * @example (just name + email): - * ```ts - * const contact: Contact = { - * name: "Jane Doe", - * email: "jane.doe@example.com" - * }; - * ``` - * - * @example (with extension): - * ```ts - * const contact: Contact = { - * name: "Internal API Team", - * email: "api-team@example.com", - * "x-slack": "#api-support" - * }; - * ``` - */ -export interface Contact extends Extension { - /** - * The identifying name of the contact person/organization. - * - * @example "API Support" - * @example "John Doe" - */ - name?: string - - /** - * The URL pointing to the contact information. MUST be in the format of a URL. - * - * @example "http://www.example.com/support" - * @example "https://example.com/contact" - */ - url?: string - - /** - * The email address of the contact person/organization. MUST be in the format of an email address. - * - * @example "support@example.com" - * @example "contact@example.com" - */ - email?: string -} - -/** - * ----- - * License Object - * ----- - * - * License information for the exposed API. - * - * The License Object provides license information for the exposed API. It can - * include the name of the license and optionally a URL to the license text. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Required The license name used for the API - * @key `url` - Optional A URL to the license used for the API - * @key `x-${string}` - Specification Extensions - * - * @note - * The `name` field is required. The `url` field is optional but recommended. - * In OpenAPI 3.0.1+, the `url` field was clarified to must be in the format - * of a URL when provided. - * - * ----- - * Examples - * ----- - * - * @example (MIT License): - * ```ts - * const license: License = { - * name: "MIT License", - * url: "https://opensource.org/license/mit/" - * }; - * ``` - * - * @example (Apache 2.0): - * ```ts - * const license: License = { - * name: "Apache 2.0", - * url: "http://www.apache.org/licenses/LICENSE-2.0.html" - * }; - * ``` - * - * @example (license without URL): - * ```ts - * const license: License = { - * name: "Proprietary License" - * }; - * ``` - * - * @example (with extension): - * ```ts - * const license: License = { - * name: "Custom License", - * url: "https://example.com/license", - * "x-license-version": "1.0" - * }; - * ``` - */ -export interface License extends Extension { - /** - * The license name used for the API. This field is required. - * - * @example "MIT License" - * @example "Apache 2.0" - * @example "Proprietary License" - */ - name: LicenseName - - /** - * A URL to the license used for the API. MUST be in the format of a URL. - * - * @example "https://opensource.org/license/mit/" - * @example "http://www.apache.org/licenses/LICENSE-2.0.html" - * @example "https://example.com/licenses/proprietary-1.0" - */ - url?: LicenseURL -} diff --git a/3.0.x/paths.ts b/3.0.x/paths.ts deleted file mode 100644 index 845ad3a..0000000 --- a/3.0.x/paths.ts +++ /dev/null @@ -1,1206 +0,0 @@ -import type { Extension } from "./extensions" -import type { Reference } from "./references" -import type { ExternalDocumentation } from "./external-documentation" -import type { Schema } from "./schema" -import type { Server } from "./servers" -import type { SecurityRequirement } from "./security" - -/** - * ----- - * Path Item Object - * ----- - * - * Describes the operations available on a single path. - * A Path Item MAY be empty, due to ACL constraints. - * - * The Path Item Object describes the operations available on a single path. It can - * contain a summary and description that apply to all operations on the path, as well - * as individual operation definitions for each HTTP method. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item} | - * - * ----- - * Fields - * ----- - * - * @key `$ref` - Optional Allows for an external definition of this path item - * @key `summary` - Optional An optional, string summary, intended to apply to all operations in this path - * @key `description` - Optional An optional, string description, intended to apply to all operations in this path - * @key `get` - Optional A definition of a GET operation on this path - * @key `put` - Optional A definition of a PUT operation on this path - * @key `post` - Optional A definition of a POST operation on this path - * @key `delete` - Optional A definition of a DELETE operation on this path - * @key `options` - Optional A definition of an OPTIONS operation on this path - * @key `head` - Optional A definition of a HEAD operation on this path - * @key `patch` - Optional A definition of a PATCH operation on this path - * @key `trace` - Optional A definition of a TRACE operation on this path - * @key `servers` - Optional An alternative server array to service all operations in this path - * @key `parameters` - Optional A list of parameters that are applicable for all the operations described under this path - * @key `x-${string}` - Specification Extensions - * - * @note - * All operation fields are optional. Parameters can be overridden at the operation level. - * In OpenAPI 3.0.1+, the `servers` property was clarified to allow alternative server - * arrays that override the global servers for operations on this specific path. - * - * ----- - * Examples - * ----- - * - * @example (simple path item): - * ```ts - * const pathItem: PathItemObject = { - * get: { - * summary: "List users", - * responses: { - * "200": { - * description: "A list of users", - * content: { - * "application/json": { - * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } - * } - * } - * } - * } - * } - * }; - * ``` - * - * @example (path item with shared parameters): - * ```ts - * const pathItem: PathItemObject = { - * summary: "User management operations", - * parameters: [ - * { name: "userId", in: "path", required: true, schema: { type: "string" } } - * ], - * get: { summary: "Get user" }, - * put: { summary: "Update user" }, - * delete: { summary: "Delete user" } - * }; - * ``` - */ -export type PathItemObject = - | ({ - /** - * Allows for an external definition of this path item. The referenced structure - * MUST be in the format of a Path Item Object. - */ - $ref?: string - - /** - * An optional, string summary, intended to apply to all operations in this path. - * - * @example "User management operations" - */ - summary?: string - - /** - * An optional, string description, intended to apply to all operations in this path. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "Operations for managing users in the system" - */ - description?: string - - /** - * A definition of a GET operation on this path. - * - * @example { summary: "Get users", responses: { "200": { description: "Success" } } } - */ - get?: Operation - - /** - * A definition of a PUT operation on this path. - * - * @example { summary: "Update user", responses: { "200": { description: "Success" } } } - */ - put?: Operation - - /** - * A definition of a POST operation on this path. - * - * @example { summary: "Create user", responses: { "201": { description: "Created" } } } - */ - post?: Operation - - /** - * A definition of a DELETE operation on this path. - * - * @example { summary: "Delete user", responses: { "204": { description: "No Content" } } } - */ - delete?: Operation - - /** - * A definition of an OPTIONS operation on this path. - * - * @example { summary: "Get options", responses: { "200": { description: "Options" } } } - */ - options?: Operation - - /** - * A definition of a HEAD operation on this path. - * - * @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } } - */ - head?: Operation - - /** - * A definition of a PATCH operation on this path. - * - * @example { summary: "Partially update user", responses: { "200": { description: "Success" } } } - */ - patch?: Operation - - /** - * A definition of a TRACE operation on this path. - * - * @example { summary: "Trace request", responses: { "200": { description: "Success" } } } - */ - trace?: Operation - - /** - * An alternative server array to service all operations in this path. - * - * @example [{ url: "https://api.example.com/v1" }] - */ - servers?: Server[] - - /** - * A list of parameters that are applicable for all the operations described - * under this path. These parameters can be overridden at the operation level, - * but cannot be removed there. The list MUST NOT include duplicated parameters. - * A unique parameter is defined by a combination of a name and location. - * - * @example [{ name: "limit", in: "query", schema: { type: "integer" } }] - */ - parameters?: Array - } & Extension) - | Reference - -/** - * ----- - * Operation Object - * ----- - * - * Describes a single API operation on a path. - * - * The Operation Object describes a single API operation on a path. It contains - * information about the operation including its parameters, request body, responses, - * and security requirements. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation} | - * - * ----- - * Fields - * ----- - * - * @key `tags` - Optional A list of tags for API documentation control - * @key `summary` - Optional A short summary of what the operation does - * @key `description` - Optional A verbose explanation of the operation behavior - * @key `externalDocs` - Optional Additional external documentation for this operation - * @key `operationId` - Optional Unique string used to identify the operation - * @key `parameters` - Optional A list of parameters that are applicable for this operation - * @key `requestBody` - Optional The request body applicable for this operation - * @key `responses` - Required The list of possible responses as they are returned from executing this operation - * @key `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation - * @key `deprecated` - Optional Declares this operation to be deprecated - * @key `security` - Optional A declaration of which security mechanisms can be used for this operation - * @key `servers` - Optional An alternative server array to service this operation - * @key `x-${string}` - Specification Extensions - * - * @note - * The `responses` field is required and MUST contain at least one response. - * In OpenAPI 3.0.1+, the `operationId` field was clarified to be case-sensitive - * and must be unique across all operations in the API. The `servers` property - * was clarified to allow alternative server arrays that override the global - * servers for this specific operation. - * - * ----- - * Examples - * ----- - * - * @example (simple operation): - * ```ts - * const operation: Operation = { - * summary: "Get users", - * responses: { - * "200": { - * description: "A list of users", - * content: { - * "application/json": { - * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } - * } - * } - * } - * } - * }; - * ``` - * - * @example (operation with request body): - * ```ts - * const operation: Operation = { - * summary: "Create user", - * operationId: "createUser", - * requestBody: { - * description: "User data", - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/User" } - * } - * } - * }, - * responses: { - * "201": { - * description: "User created", - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/User" } - * } - * } - * } - * } - * }; - * ``` - */ -export interface Operation extends Extension { - /** - * A list of tags for API documentation control. Tags can be used for logical - * grouping of operations by resources or any other qualifier. - * - * @example ["users", "authentication"] - * @example ["pets"] - */ - tags?: string[] - - /** - * A short summary of what the operation does. For maximum readability in - * OpenAPI-UI, this field SHOULD be less than 120 characters. - * - * @example "Get user by ID" - * @example "Create a new pet" - */ - summary?: string - - /** - * A verbose explanation of the operation behavior. CommonMark syntax MAY be used - * for rich text representation. - * - * @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information." - */ - description?: string - - /** - * Additional external documentation for this operation. - * - * @example { description: "Find out more about this operation", url: "https://example.com/docs" } - */ - externalDocs?: ExternalDocumentation - - /** - * Unique string used to identify the operation. The id MUST be unique among - * all operations described in the API. Tools and libraries MAY use the - * operationId to uniquely identify an operation, therefore, it is recommended - * to follow common programming naming conventions. - * - * @example "getUserById" - * @example "createPet" - */ - operationId?: string - - /** - * A list of parameters that are applicable for this operation. If a parameter - * is already defined at the Path Item, the new definition will override it - * but can never remove it. The list MUST NOT include duplicated parameters. - * A unique parameter is defined by a combination of a name and location. - * - * @example [{ name: "id", in: "path", required: true, schema: { type: "string" } }] - */ - parameters?: Array - - /** - * The request body applicable for this operation. The requestBody is only - * supported in HTTP methods where the HTTP 1.1 specification has explicitly - * defined semantics for request bodies. - * - * @example { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } - */ - requestBody?: RequestBody | Reference - - /** - * The list of possible responses as they are returned from executing this operation. - * This field MUST be present and MUST contain at least one response. - * - * @example { "200": { description: "Success", content: { "application/json": { schema: { type: "object" } } } } } - */ - responses: Record - - /** - * A map of possible out-of band callbacks related to the parent operation. - * The key is a unique identifier for the Callback Object. Each value in the map - * is a Callback Object that describes a request that may be initiated by the API - * provider and the expected responses. - * - * @example { "myCallback": { "{$request.body#/callbackUrl}": { post: { ... } } } } - */ - callbacks?: Record - - /** - * Declares this operation to be deprecated. Consumers SHOULD refrain from usage - * of the declared operation. Default value is false. - * - * @default false - * @example true - */ - deprecated?: boolean - - /** - * A declaration of which security mechanisms can be used for this operation. - * The list of values includes alternative security requirement objects that can be used. - * Only one of the security requirement objects need to be satisfied to authorize a request. - * This definition overrides any declared top-level security. - * - * @example [{ "api_key": [] }] - * @example [{ "oauth2": ["read", "write"] }] - */ - security?: SecurityRequirement[] - - /** - * An alternative server array to service this operation. If an alternative - * server object is specified at the Path Item Object or Root level, it will - * be overridden by this value. - * - * @example [{ url: "https://api.example.com/v1" }] - */ - servers?: Server[] -} - -/** - * ----- - * Parameter Object - * ----- - * - * Describes a single operation parameter. - * A unique parameter is defined by a combination of a name and location. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Required The name of the parameter - * @key `in` - Required The location of the parameter - * @key `description` - Optional A brief description of the parameter - * @key `required` - Optional Determines whether this parameter is mandatory - * @key `deprecated` - Optional Specifies that a parameter is deprecated - * @key `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters - * @key `style` - Optional Describes how the parameter value will be serialized - * @key `explode` - Optional When this is true, parameter values generate separate parameters - * @key `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters - * @key `schema` - Optional The schema defining the type used for the parameter - * @key `example` - Optional Example of the media type - * @key `examples` - Optional Examples of the media type - * @key `content` - Optional A map containing the representations for the parameter - * @key `x-${string}` - Specification Extensions - * - * @note - * The `name` and `in` fields are required. A parameter MUST contain either a `schema` property, or a `content` property, but not both. - * - * ----- - * Examples - * ----- - * - * @example (path parameter): - * ```ts - * const parameter: Parameter = { - * name: "id", - * in: "path", - * required: true, - * description: "User ID", - * schema: { type: "string" } - * }; - * ``` - * - * @example (query parameter): - * ```ts - * const parameter: Parameter = { - * name: "limit", - * in: "query", - * description: "Number of items to return", - * schema: { type: "integer", minimum: 1, maximum: 100 } - * }; - * ``` - */ -export interface Parameter extends Extension { - /** - * The name of the parameter. Parameter names are case sensitive. - * - If in is "path", the name field MUST correspond to the associated path segment - * - If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored - * - For all other cases, the name corresponds to the parameter name used by the in property - * - * @example "id" - * @example "limit" - * @example "user" - */ - name: string - - /** - * The location of the parameter. Possible values are "query", "header", "path" or "cookie". - * - * - **query**: Parameters that are appended to the URL - * - **header**: Custom headers that are expected as part of the request - * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL - * - **cookie**: Used to pass a specific cookie value to the API - * - * @example "query" - * @example "path" - * @example "header" - * @example "cookie" - */ - in: "query" | "header" | "path" | "cookie" - - /** - * A brief description of the parameter. This could contain examples of use. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "User ID to retrieve" - * @example "Number of items to return" - */ - description?: string - - /** - * Determines whether this parameter is mandatory. If the parameter location is "path", - * this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be - * included and its default value is false. - * - * @example true - * @example false - */ - required?: boolean - - /** - * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. - * - * @example true - * @example false - */ - deprecated?: boolean - - /** - * Sets the ability to pass empty-valued parameters. This is valid only for query - * parameters and allows sending a parameter with an empty value. Default value is false. - * - * @example true - * @example false - */ - allowEmptyValue?: boolean - - /** - * Describes how the parameter value will be serialized depending on the type of the parameter value. - * Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form. - * - * @example "form" - * @example "simple" - * @example "matrix" - * @example "label" - * @example "spaceDelimited" - * @example "pipeDelimited" - * @example "deepObject" - */ - style?: "matrix" | "label" | "form" | "simple" | "spaceDelimited" | "pipeDelimited" | "deepObject" - - /** - * When this is true, parameter values of type array or object generate separate parameters - * for each value of the array or key-value pair of the map. For other types of parameters - * this property has no effect. When style is form, the default value is true. - * For all other styles, the default value is false. - * - * @example true - * @example false - */ - explode?: boolean - - /** - * Determines whether the parameter value SHOULD allow reserved characters, as defined by - * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only - * applies to parameters with an in value of query. The default value is false. - * - * @example true - * @example false - */ - allowReserved?: boolean - - /** - * The schema defining the type used for the parameter. - * - * @example { type: "string" } - * @example { type: "integer", minimum: 1, maximum: 100 } - */ - schema?: Schema - - /** - * Example of the media type. The example SHOULD match the specified schema and encoding - * properties if present. The example object is mutually exclusive of the examples object. - * - * @example "example-value" - * @example 42 - */ - example?: unknown - - /** - * Examples of the media type. Each example SHOULD contain a value in the correct format - * as specified in the parameter encoding. The examples object is mutually exclusive of - * the example object. - * - * @example { "user1": { summary: "A user example", value: "user123" } } - */ - examples?: Record - - /** - * A map containing the representations for the parameter. The key is the media type - * and the value describes it. The map MUST only contain one entry. - * - * @example { "application/json": { schema: { type: "object" } } } - */ - content?: Record -} - -/** - * ----- - * Request Body Object - * ----- - * - * Describes a single request body. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#request-body-object | OpenAPI 3.0.0 Request Body} | - * - * ----- - * Fields - * ----- - * - * @key `description` - Optional A brief description of the request body - * @key `content` - Required The content of the request body - * @key `required` - Optional Determines if the request body is required in the request - * @key `x-${string}` - Specification Extensions - * - * @note - * The `content` field is required. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification has explicitly defined semantics for request bodies. - * - * ----- - * Examples - * ----- - * - * @example (simple request body): - * ```ts - * const requestBody: RequestBody = { - * description: "User data", - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/User" } - * } - * } - * }; - * ``` - */ -export interface RequestBody extends Extension { - /** - * A brief description of the request body. This could contain examples of use. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "User data to create" - * @example "Pet information" - */ - description?: string - - /** - * The content of the request body. The key is a media type or media type range - * and the value describes it. For requests that match multiple keys, only the - * most specific key is applicable. - * - * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } - */ - content: Record - - /** - * Determines if the request body is required in the request. Defaults to false. - * - * @default false - * @example true - */ - required?: boolean -} - -/** - * ----- - * Media Type Object - * ----- - * - * Each Media Type Object provides schema and examples for the media type identified by its key. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type} | - * - * ----- - * Fields - * ----- - * - * @key `schema` - Optional The schema defining the type used for the request body - * @key `example` - Optional Example of the media type - * @key `examples` - Optional Examples of the media type - * @key `encoding` - Optional A map between a property name and its encoding information - * @key `x-${string}` - Specification Extensions - * - * @note - * The `example` object is mutually exclusive of the `examples` object. - * - * ----- - * Examples - * ----- - * - * @example (simple media type): - * ```ts - * const mediaType: MediaType = { - * schema: { $ref: "#/components/schemas/User" } - * }; - * ``` - */ -export interface MediaType extends Extension { - /** - * The schema defining the type used for the request body. - * - * @example { $ref: "#/components/schemas/User" } - * @example { type: "object", properties: { name: { type: "string" } } } - */ - schema?: Schema | Reference - - /** - * Example of the media type. The example object SHOULD be in the correct format - * as specified by the media type. The example object is mutually exclusive of - * the examples object. - * - * @example { name: "John Doe", email: "john@example.com" } - */ - example?: unknown - - /** - * Examples of the media type. Each example object SHOULD match the media type - * and specified schema if present. The examples object is mutually exclusive of - * the example object. - * - * @example { "user1": { summary: "A user example", value: { name: "John" } } } - */ - examples?: Record - - /** - * A map between a property name and its encoding information. The key, being the - * property name, MUST exist in the schema as a property. The encoding object SHALL - * only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded. - * - * @example { "profileImage": { contentType: "image/png" } } - */ - encoding?: Record -} - -/** - * ----- - * Encoding Object - * ----- - * - * A single encoding definition applied to a single schema property. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding} | - * - * ----- - * Fields - * ----- - * - * @key `contentType` - Optional The Content-Type for encoding a specific property - * @key `headers` - Optional A map allowing additional information to be provided as headers - * @key `style` - Optional Describes how a specific property value will be serialized - * @key `explode` - Optional When this is true, property values generate separate parameters - * @key `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters - * @key `x-${string}` - Specification Extensions - * - * @note - * This attribute is only applicable to multipart and application/x-www-form-urlencoded request bodies. - * - * ----- - * Examples - * ----- - * - * @example (simple encoding): - * ```ts - * const encoding: Encoding = { - * contentType: "image/png" - * }; - * ``` - */ -export interface Encoding extends Extension { - /** - * The Content-Type for encoding a specific property. Default value depends on the property type. - * - * @example "image/png" - * @example "application/json" - * @example "text/plain" - */ - contentType?: string - - /** - * A map allowing additional information to be provided as headers, for example - * Content-Disposition. Content-Type is described separately and SHALL be ignored in this section. - * - * @example { "Content-Disposition": { schema: { type: "string" } } } - */ - headers?: Record - - /** - * Describes how a specific property value will be serialized depending on its type. - * See Parameter Object for details on the style property. The behavior follows the - * same values as query parameters, including default values. - * - * @example "form" - * @example "simple" - */ - style?: "form" | "spaceDelimited" | "pipeDelimited" | "deepObject" - - /** - * When this is true, property values of type array or object generate separate parameters - * for each value of the array, or key-value-pair of the map. For other types of properties - * this property has no effect. When style is form, the default value is true. - * For all other styles, the default value is false. - * - * @example true - * @example false - */ - explode?: boolean - - /** - * Determines whether the parameter value SHOULD allow reserved characters, as defined by - * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. - * - * @example true - * @example false - */ - allowReserved?: boolean -} - -/** - * ----- - * Response Object - * ----- - * - * Describes a single response from an API Operation, including design-time, static - * links to operations based on the response. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response} | - * - * ----- - * Fields - * ----- - * - * @key `description` - Required A short description of the response - * @key `headers` - Optional Maps a header name to its definition - * @key `content` - Optional A map containing descriptions of potential response payloads - * @key `links` - Optional A map of operations links that can be followed from the response - * @key `x-${string}` - Specification Extensions - * - * @note - * The `description` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple response): - * ```ts - * const response: Response = { - * description: "A list of users", - * content: { - * "application/json": { - * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } - * } - * } - * }; - * ``` - */ -export interface Response extends Extension { - /** - * A short description of the response. CommonMark syntax MAY be used for rich text representation. - * This field is required. - * - * @example "User successfully retrieved" - * @example "Bad request - invalid input parameters" - * @example "Internal server error" - */ - description: string - - /** - * Maps a header name to its definition. RFC7230 states header names are case insensitive. - * If a response header is defined with the name "Content-Type", it SHALL be ignored. - * - * @example { "X-RateLimit-Limit": { schema: { type: "integer" } } } - */ - headers?: Record - - /** - * A map containing descriptions of potential response payloads. The key is a media type - * or media type range and the value describes it. For responses that match multiple keys, - * only the most specific key is applicable. - * - * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } - */ - content?: Record - - /** - * A map of operations links that can be followed from the response. The key of the map - * is a short name for the link, following the naming constraints of the names for Component Objects. - * - * @example { "GetUserByUserId": { operationId: "getUserById", parameters: { userId: "$response.body#/id" } } } - */ - links?: Record -} - -/** - * ----- - * Header Object - * ----- - * - * The Header Object follows the structure of the Parameter Object with the following changes: - * 1. name MUST NOT be specified, it is given in the corresponding headers map. - * 2. in MUST NOT be specified, it is implicitly in header. - * 3. All traits that are affected by the location MUST be applicable to a location of header. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header} | - * - * ----- - * Examples - * ----- - * - * @example (simple header): - * ```ts - * const header: Header = { - * description: "The number of allowed requests in the current period", - * schema: { type: "integer" } - * }; - * ``` - */ -export interface Header extends Extension { - /** - * A brief description of the header. CommonMark syntax MAY be used for rich text representation. - * - * @example "Rate limit for the current period" - * @example "Content type of the response" - */ - description?: string - - /** - * Determines whether this header is mandatory. The property MAY be included and its default value is false. - * - * @example true - * @example false - */ - required?: boolean - - /** - * Specifies that a header is deprecated and SHOULD be transitioned out of usage. - * - * @example true - * @example false - */ - deprecated?: boolean - - /** - * Sets the ability to pass empty-valued headers. This is valid only for headers - * and allows sending a header with an empty value. Default value is false. - * - * @example true - * @example false - */ - allowEmptyValue?: boolean - - /** - * Describes how the header value will be serialized. The default value is simple. - * - * @example "simple" - */ - style?: "simple" - - /** - * When this is true, header values of type array or object generate separate headers - * for each value of the array or key-value pair of the map. For other types of headers - * this property has no effect. The default value is false. - * - * @example true - * @example false - */ - explode?: boolean - - /** - * The schema defining the type used for the header. - * - * @example { type: "integer" } - * @example { type: "string" } - */ - schema?: Schema | Reference - - /** - * Example of the media type. The example SHOULD match the specified schema and encoding - * properties if present. The example object is mutually exclusive of the examples object. - * - * @example "example-value" - * @example 42 - */ - example?: unknown - - /** - * Examples of the media type. Each example SHOULD contain a value in the correct format - * as specified in the header encoding. The examples object is mutually exclusive of - * the example object. - * - * @example { "header1": { summary: "A header example", value: "value123" } } - */ - examples?: Record - - /** - * A map containing the representations for the header. The key is the media type - * and the value describes it. The map MUST only contain one entry. - * - * @example { "application/json": { schema: { type: "object" } } } - */ - content?: Record -} - -/** - * ----- - * Callback Object - * ----- - * - * A map of possible out-of band callbacks related to the parent operation. - * Each value in the map is a Path Item Object that describes a set of requests - * that may be initiated by the API provider and the expected responses. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#callback-object | OpenAPI 3.0.0 Callback} | - * - * ----- - * Examples - * ----- - * - * @example (simple callback): - * ```ts - * const callback: Callback = { - * "{$request.body#/callbackUrl}": { - * post: { - * requestBody: { - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/SomePayload" } - * } - * } - * }, - * responses: { - * "200": { - * description: "webhook successfully processed" - * } - * } - * } - * } - * }; - * ``` - */ -export type Callback = Record - -/** - * ----- - * Link Object - * ----- - * - * The Link object represents a possible design-time link for a response. - * The presence of a link does not guarantee the caller's ability to successfully invoke it, - * rather it provides a known relationship and traversal mechanism between responses and other operations. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link} | - * - * ----- - * Fields - * ----- - * - * @key `operationRef` - Optional A relative or absolute reference to an OAS operation - * @key `operationId` - Optional The name of an existing, resolvable OAS operation - * @key `parameters` - Optional A map representing parameters to pass to an operation - * @key `requestBody` - Optional A literal value or expression to use as a request body - * @key `description` - Optional A description of the link - * @key `server` - Optional A server object to be used by the target operation - * @key `x-${string}` - Specification Extensions - * - * @note - * A linked operation MUST be identified using either an operationRef or operationId. - * - * ----- - * Examples - * ----- - * - * @example (link with operationId): - * ```ts - * const link: Link = { - * operationId: "getUserById", - * parameters: { - * userId: "$response.body#/id" - * } - * }; - * ``` - */ -export interface Link extends Extension { - /** - * A relative or absolute reference to an OAS operation. This field is mutually - * exclusive of the operationId field, and MUST point to an Operation Object. - * - * @example "#/paths/~12.0~1repositories~1{username}/get" - * @example "https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get" - */ - operationRef?: string - - /** - * The name of an existing, resolvable OAS operation, as defined with a unique operationId. - * This field is mutually exclusive of the operationRef field. - * - * @example "getUserById" - * @example "createPet" - */ - operationId?: string - - /** - * A map representing parameters to pass to an operation as specified with operationId - * or identified via operationRef. The key is the parameter name to be used, whereas - * the value can be a constant or an expression to be evaluated and passed to the linked operation. - * - * @example { userId: "$response.body#/id" } - * @example { limit: 10 } - */ - parameters?: Record - - /** - * A literal value or expression to use as a request body when calling the target operation. - * - * @example { name: "John Doe" } - * @example "$request.body#/user" - */ - requestBody?: unknown - - /** - * A description of the link. CommonMark syntax MAY be used for rich text representation. - * - * @example "Get user by ID" - * @example "Create a new pet" - */ - description?: string - - /** - * A server object to be used by the target operation. - * - * @example { url: "https://api.example.com/v1" } - */ - server?: Server -} - -/** - * ----- - * Example Object - * ----- - * - * In all cases, the example value is expected to be compatible with the type schema - * of its associated value. Tooling implementations MAY choose to validate compatibility - * automatically, and reject the example value(s) if incompatible. - * - * | Version | Reference | - * |---|-----| - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example} | - * - * ----- - * Fields - * ----- - * - * @key `summary` - Optional Short description for the example - * @key `description` - Optional Long description for the example - * @key `value` - Optional Embedded literal example - * @key `externalValue` - Optional A URL that points to the literal example - * @key `x-${string}` - Specification Extensions - * - * @note - * The `value` field and `externalValue` field are mutually exclusive. - * - * ----- - * Examples - * ----- - * - * @example (simple example): - * ```ts - * const example: Example = { - * summary: "A user example", - * value: { name: "John Doe", email: "john@example.com" } - * }; - * ``` - */ -export interface Example extends Extension { - /** - * Short description for the example. - * - * @example "A user example" - * @example "An error response" - */ - summary?: string - - /** - * Long description for the example. CommonMark syntax MAY be used for rich text representation. - * - * @example "A complete user object with all fields populated" - * @example "An error response when the user is not found" - */ - description?: string - - /** - * Embedded literal example. The value field and externalValue field are mutually exclusive. - * To represent examples of media types that cannot naturally represented in JSON or YAML, - * use a string value to contain the example, escaping where necessary. - * - * @example { name: "John Doe", email: "john@example.com" } - * @example "example string value" - */ - value?: unknown - - /** - * A URL that points to the literal example. This provides the capability to reference - * examples that cannot easily be included in JSON or YAML documents. The value field - * and externalValue field are mutually exclusive. - * - * @example "https://example.com/examples/user-example.json" - * @example "https://example.com/examples/error-example.xml" - */ - externalValue?: string -} diff --git a/3.0.x/references.ts b/3.0.x/references.ts deleted file mode 100644 index 5436404..0000000 --- a/3.0.x/references.ts +++ /dev/null @@ -1,49 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * Reference Object - * ----- - * - * A simple object to allow referencing other components in the specification, - * internally and externally. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#reference-object | OpenAPI 3.0.4 Reference} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#reference-object | OpenAPI 3.0.3 Reference} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#reference-object | OpenAPI 3.0.2 Reference} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#reference-object | OpenAPI 3.0.1 Reference} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#reference-object | OpenAPI 3.0.0 Reference} | - * - * ----- - * Fields - * ----- - * - * @key `$ref` - Required The reference string - * @key `x-${string}` - Specification Extensions - * - * @note - * The `$ref` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple reference): - * ```ts - * const reference: Reference = { - * $ref: "#/components/schemas/User" - * }; - * ``` - */ -export interface Reference extends Extension { - /** - * The reference string. MUST be a valid JSON Reference. - * - * @example "#/components/schemas/User" - * @example "#/components/responses/NotFound" - * @example "#/components/parameters/LimitParam" - */ - $ref: string -} diff --git a/3.0.x/security.ts b/3.0.x/security.ts deleted file mode 100644 index 2e53f9a..0000000 --- a/3.0.x/security.ts +++ /dev/null @@ -1,225 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * Security Scheme Object - * ----- - * - * Defines a security scheme that can be used by the operations. - * Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), - * OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, - * and OpenID Connect Discovery. - * - * The Security Scheme Object defines a security scheme that can be used by the operations. - * It supports various authentication methods including HTTP authentication, API keys, - * OAuth2 flows, and OpenID Connect Discovery. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Required The type of the security scheme - * @key `description` - Optional A short description for security scheme - * @key `name` - Optional The name of the header, query or cookie parameter to be used - * @key `in` - Optional The location of the API key - * @key `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header - * @key `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted - * @key `flows` - Optional An object containing configuration information for the flow types supported - * @key `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values - * @key `x-${string}` - Specification Extensions - * - * @note - * The `type` field is required. The `name` and `in` fields are required for apiKey type. - * In OpenAPI 3.0.1+, the `bearerFormat` field was clarified to be a hint to the client - * about how the bearer token is formatted, and the `openIdConnectUrl` field was clarified - * to be a URL that can be used to discover OAuth2 configuration values. - * - * ----- - * Examples - * ----- - * - * @example (API key): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "apiKey", - * in: "header", - * name: "X-API-Key" - * }; - * ``` - * - * @example (OAuth2): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "oauth2", - * flows: { - * authorizationCode: { - * authorizationUrl: "https://example.com/oauth/authorize", - * tokenUrl: "https://example.com/oauth/token", - * scopes: { - * "read": "Read access", - * "write": "Write access" - * } - * } - * } - * }; - * ``` - * - * @example (HTTP Bearer): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "http", - * scheme: "bearer", - * bearerFormat: "JWT" - * }; - * ``` - * - * @example (OpenID Connect): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "openIdConnect", - * openIdConnectUrl: "https://example.com/.well-known/openid_configuration" - * }; - * ``` - */ -export interface SecurityScheme extends Extension { - /** - * The type of the security scheme. This field is required. - * - * @example "apiKey" - * @example "http" - * @example "oauth2" - * @example "openIdConnect" - */ - type: "apiKey" | "http" | "oauth2" | "openIdConnect" - - /** - * A short description for security scheme. CommonMark syntax MAY be used for rich text representation. - * - * @example "API key authentication" - * @example "OAuth 2.0 authentication" - */ - description?: string - - /** - * The name of the header, query or cookie parameter to be used. - * - * @example "X-API-Key" - * @example "Authorization" - */ - name?: string - - /** - * The location of the API key. Valid values are "query", "header" or "cookie". - * - * @example "query" - * @example "header" - * @example "cookie" - */ - in?: "query" | "header" | "cookie" - - /** - * The name of the HTTP Authorization scheme to be used in the Authorization header. - * - * @example "bearer" - * @example "basic" - */ - scheme?: string - - /** - * A hint to the client to identify how the bearer token is formatted. - * - * @example "JWT" - * @example "Bearer" - */ - bearerFormat?: string - - /** - * An object containing configuration information for the flow types supported. - * - * @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } } - */ - flows?: OAuthFlows - - /** - * OpenId Connect URL to discover OAuth2 configuration values. - * - * @example "https://example.com/.well-known/openid_configuration" - */ - openIdConnectUrl?: string -} - -export interface OAuthFlows extends Extension { - /** - * Configuration for the OAuth Implicit flow. - * - * @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { read: "Read access" } } - */ - implicit?: OAuthFlow - - /** - * Configuration for the OAuth Resource Owner Password flow. - * - * @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } } - */ - password?: OAuthFlow - - /** - * Configuration for the OAuth Client Credentials flow. - * - * @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } } - */ - clientCredentials?: OAuthFlow - - /** - * Configuration for the OAuth Authorization Code flow. - * - * @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } } - */ - authorizationCode?: OAuthFlow -} - -export interface OAuthFlow extends Extension { - /** - * The authorization URL to be used for this flow. This MUST be in the form of a URL. - * - * @example "https://example.com/oauth/authorize" - * @example "https://api.example.com/oauth/authorize" - */ - authorizationUrl?: string - - /** - * The token URL to be used for this flow. This MUST be in the form of a URL. - * - * @example "https://example.com/oauth/token" - * @example "https://api.example.com/oauth/token" - */ - tokenUrl?: string - - /** - * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. - * - * @example "https://example.com/oauth/refresh" - * @example "https://api.example.com/oauth/refresh" - */ - refreshUrl?: string - - /** - * The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - * - * @example { "read": "Read access", "write": "Write access" } - * @example { "admin": "Administrative access" } - */ - scopes?: Record -} - -export interface SecurityRequirement { - [schemeName: string]: string[] -} diff --git a/3.0.x/servers.ts b/3.0.x/servers.ts deleted file mode 100644 index 3bcb1aa..0000000 --- a/3.0.x/servers.ts +++ /dev/null @@ -1,197 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * Server Object - * ----- - * - * An object representing a Server. - * - * The Server Object represents a server that hosts the API. It can contain a URL, - * description, and server variables for URL template substitution. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-object | OpenAPI 3.0.4 Server} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-object | OpenAPI 3.0.3 Server} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-object | OpenAPI 3.0.2 Server} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-object | OpenAPI 3.0.1 Server} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-object | OpenAPI 3.0.0 Server} | - * - * ----- - * Fields - * ----- - * - * @key `url` - Required A URL to the target host - * @key `description` - Optional An optional string describing the host designated by the URL - * @key `variables` - Optional A map between a variable name and its value - * @key `x-${string}` - Specification Extensions - * - * @note - * The `url` field is required. The `url` supports Server Variables and MAY be relative. - * In OpenAPI 3.0.1+, the `url` field was clarified to support Server Variables and - * MAY be relative to indicate that the host location is relative to the location - * where the OpenAPI document is being served. - * - * ----- - * Examples - * ----- - * - * @example (simple server): - * ```ts - * const server: Server = { - * url: "https://development.gigantic-server.com/v1", - * description: "Development server" - * }; - * ``` - * - * @example (server with variables): - * ```ts - * const server: Server = { - * url: "https://{username}.gigantic-server.com:{port}/{basePath}", - * description: "The production API server", - * variables: { - * username: { - * default: "demo", - * description: "this value is assigned by the service provider" - * }, - * port: { - * enum: ["8443", "443"], - * default: "8443" - * }, - * basePath: { - * default: "v2" - * } - * } - * }; - * ``` - * - * @example (relative server): - * ```ts - * const server: Server = { - * url: "/v1", - * description: "Relative server URL" - * }; - * ``` - */ -export interface Server extends Extension { - /** - * A URL to the target host. This URL supports Server Variables and MAY be relative, - * to indicate that the host location is relative to the location where the OpenAPI - * document is being served. Variable substitutions will be made when a variable - * is named in {brackets}. - * - * @example "https://api.example.com/v1" - * @example "https://{username}.example.com:{port}/{basePath}" - * @example "/v1" - */ - url: string - - /** - * An optional string describing the host designated by the URL. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "Development server" - * @example "Production server" - */ - description?: string - - /** - * A map between a variable name and its value. The value is used for substitution - * in the server's URL template. - * - * @example { username: { default: "demo" }, port: { default: "8080" } } - */ - variables?: Record -} - -/** - * ----- - * Server Variable Object - * ----- - * - * An object representing a Server Variable for server URL template substitution. - * - * The Server Variable Object represents a server variable for server URL template - * substitution. It can contain an enumeration of values, a default value, and - * a description. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-variable-object | OpenAPI 3.0.4 Server Variable} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-variable-object | OpenAPI 3.0.3 Server Variable} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-variable-object | OpenAPI 3.0.2 Server Variable} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-variable-object | OpenAPI 3.0.1 Server Variable} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-variable-object | OpenAPI 3.0.0 Server Variable} | - * - * ----- - * Fields - * ----- - * - * @key `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set - * @key `default` - Required The default value to use for substitution - * @key `description` - Optional An optional description for the server variable - * @key `x-${string}` - Specification Extensions - * - * @note - * The `default` field is required. Unlike the Schema Object's default, this value MUST be provided by the consumer. - * In OpenAPI 3.0.1+, the `default` field was clarified to be the default value to use - * for substitution, and to send, if an alternate value is not supplied. - * - * ----- - * Examples - * ----- - * - * @example (simple variable): - * ```ts - * const variable: ServerVariable = { - * default: "v2", - * description: "API version" - * }; - * ``` - * - * @example (variable with enum): - * ```ts - * const variable: ServerVariable = { - * enum: ["8443", "443"], - * default: "8443", - * description: "Port number" - * }; - * ``` - * - * @example (variable with extension): - * ```ts - * const variable: ServerVariable = { - * default: "production", - * description: "Environment", - * "x-environment-type": "production" - * }; - * ``` - */ -export interface ServerVariable extends Extension { - /** - * An enumeration of string values to be used if the substitution options are from a limited set. - * - * @example ["8443", "443"] - * @example ["v1", "v2", "v3"] - */ - enum?: string[] - - /** - * The default value to use for substitution, and to send, if an alternate value is not supplied. - * Unlike the Schema Object's default, this value MUST be provided by the consumer. - * - * @example "demo" - * @example "8443" - * @example "v2" - */ - default: string - - /** - * An optional description for the server variable. CommonMark syntax MAY be used for rich text representation. - * - * @example "this value is assigned by the service provider" - * @example "Port number for the server" - */ - description?: string -} diff --git a/3.0.x/spec.ts b/3.0.x/spec.ts deleted file mode 100644 index 27783fa..0000000 --- a/3.0.x/spec.ts +++ /dev/null @@ -1,200 +0,0 @@ -import type { Extension } from "./extensions" - -// Import all the major component types -import type { Info } from "./info" -import type { - PathItemObject, - Operation, - Parameter, - Response, - Header, - RequestBody, - MediaType, - Encoding, - Callback, - Link, - Example -} from "./paths" -import type { - Schema, - Discriminator -} from "./schema" -import type { XML } from "./xml" -import type { Components } from "./components" -import type { - Server, - ServerVariable -} from "./servers" -import type { Tag } from "./tags" -import type { ExternalDocumentation } from "./external-documentation" -import type { Reference } from "./references" -import type { - SecurityScheme, - SecurityRequirement -} from "./security" - -/** - * ----- - * OpenAPI Object - * ----- - * - * Root OpenAPI 3.0 Schema (OpenAPI Object) - * - * This is the root document object of the OpenAPI specification. It contains - * all the metadata about the API being described. This object is based on the - * JSON Schema Specification Wright Draft 00 and uses a predefined subset of it. - * - * The OpenAPI Object is the root of the specification document and contains - * all the information about the API, including its metadata, available paths, - * data models, security schemes, and more. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 OpenAPI Object} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 OpenAPI Object} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 OpenAPI Object} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 OpenAPI Object} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 OpenAPI Object} | - * - * ----- - * Fields - * ----- - * - * @key `openapi` - Required Specifies the OpenAPI specification version - * @key `info` - Required Provides metadata about the API - * @key `servers` - Optional An array of Server Objects - * @key `paths` - Required The available paths and operations for the API - * @key `components` - Optional An element to hold various schemas - * @key `security` - Optional A declaration of security mechanisms - * @key `tags` - Optional A list of tags used by the specification - * @key `externalDocs` - Optional Additional external documentation - * @key `x-${string}` - Specification Extensions - * - * @note - * The `openapi` field is required and must be "3.0.0" for this specification. - * The `info` and `paths` fields are also required. - * - * ----- - * Examples - * ----- - * @example - * ```typescript - * const openapi: Specification = { - * openapi: "3.0.0", - * info: { - * title: "Sample Pet Store App", - * description: "This is a sample server for a pet store.", - * version: "1.0.1" - * }, - * servers: [ - * { - * url: "https://petstore.swagger.io/v2", - * description: "Petstore server" - * } - * ], - * paths: { - * "/pets": { - * get: { - * summary: "List all pets", - * responses: { - * "200": { - * description: "A list of pets", - * content: { - * "application/json": { - * schema: { - * type: "array", - * items: { $ref: "#/components/schemas/Pet" } - * } - * } - * } - * } - * } - * } - * } - * }, - * components: { - * schemas: { - * Pet: { - * type: "object", - * properties: { - * id: { type: "integer", format: "int64" }, - * name: { type: "string" }, - * tag: { type: "string" } - * } - * } - * } - * } - * } - * ``` - */ -export type Specification = { - /** - * Specifies the OpenAPI specification version being used. - * Must be "3.0.0" for this specification. - */ - openapi: "3.0.0" - - /** - * Provides metadata about the API. The metadata can be used by the clients - * if needed, and can be presented in the OpenAPI-UI for convenience. - */ - info: Info - - /** - * An array of Server Objects, which provide connectivity information to a target server. - * If the servers property is not provided, or is an empty array, the default value - * would be a Server Object with a url value of "/". - * - * @example [{ url: "https://api.example.com/v1", description: "Production server" }] - * @example [{ url: "https://staging-api.example.com/v1", description: "Staging server" }] - */ - servers?: Server[] - - /** - * The available paths and operations for the API. This is the root of the - * Path Item Object. It does not define a path or a basePath, they are defined - * in the Paths Object. A relative path to an individual endpoint. The field - * name MUST begin with a slash. The path is appended to the basePath in order - * to construct the full URL. Path templating is allowed. - * - * @example { "/users": { get: { ... } } } - * @example { "/users/{id}": { get: { ... } } } - */ - paths: Record - - /** - * An element to hold various schemas for the specification. - * - * @example { schemas: { User: { type: "object", properties: { ... } } } } - */ - components?: Components - - /** - * A declaration of which security mechanisms can be used across the API. - * The list of values includes alternative security requirement objects that can be used. - * Only one of the security requirement objects need to be satisfied to authorize a request. - * Individual operations can override this definition. - * - * @example [{ "api_key": [] }] - * @example [{ "oauth2": ["read", "write"] }] - */ - security?: SecurityRequirement[] - - /** - * A list of tags used by the specification with additional metadata. - * The order of the tags can be used to reflect on their order by the - * parsing tools. Not all tags that are used by the Operation Object must - * be declared. The tags that are not declared may be organized randomly - * or based on the tools' logic. Each tag name in the list MUST be unique. - * - * @example [{ name: "users", description: "User management" }] - */ - tags?: Tag[] - - /** - * Additional external documentation. - * - * @example { description: "Find out more about our API", url: "https://example.com/docs" } - */ - externalDocs?: ExternalDocumentation -} & Extension diff --git a/3.0.x/tags.ts b/3.0.x/tags.ts deleted file mode 100644 index 67bf5c3..0000000 --- a/3.0.x/tags.ts +++ /dev/null @@ -1,84 +0,0 @@ -import type { Extension } from "./extensions" -import type { ExternalDocumentation } from "./external-documentation" - -/** - * ----- - * Tag Object - * ----- - * - * Adds metadata to a single tag that is used by the Tag Object. - * It is not mandatory to have a Tag Object per tag used there. - * - * Tags provide a way to organize and categorize API operations, making it easier - * for developers to understand and navigate the API. They are commonly used to - * group operations by resource type, functionality, or any other logical division. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#tag-object | OpenAPI 3.0.4 Tag} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#tag-object | OpenAPI 3.0.3 Tag} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#tag-object | OpenAPI 3.0.2 Tag} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#tag-object | OpenAPI 3.0.1 Tag} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#tag-object | OpenAPI 3.0.0 Tag} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Required The name of the tag - * @key `description` - Optional A short description for the tag - * @key `externalDocs` - Optional Additional external documentation for this tag - * @key `x-${string}` - Specification Extensions - * - * @note - * The `name` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple tag): - * ```ts - * const tag: Tag = { - * name: "users", - * description: "User management operations" - * }; - * ``` - * - * @example (tag with external documentation): - * ```ts - * const tag: Tag = { - * name: "pets", - * description: "Pet store operations", - * externalDocs: { - * description: "Find out more about pet management", - * url: "https://example.com/docs/pets" - * } - * }; - * ``` - */ -export interface Tag extends Extension { - /** - * The name of the tag. This field is required. - * - * @example "users" - * @example "pets" - * @example "authentication" - */ - name: string - - /** - * A short description for the tag. CommonMark syntax MAY be used for rich text representation. - * - * @example "User management operations" - * @example "Pet store operations" - */ - description?: string - - /** - * Additional external documentation for this tag. - * - * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } - */ - externalDocs?: ExternalDocumentation -} diff --git a/3.0.x/xml.ts b/3.0.x/xml.ts deleted file mode 100644 index 367185d..0000000 --- a/3.0.x/xml.ts +++ /dev/null @@ -1,91 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * XML Object - * ----- - * - * A metadata object that allows for more fine-tuned XML model definitions. - * When using arrays, XML element names are not inferred (for singular/plural forms) - * and the name property should be used to add that information. - * - * | Version | Reference | - * |---|-----| - * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML} | - * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML} | - * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML} | - * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML} | - * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Optional Replaces the name of the element/attribute used for the described schema property - * @key `namespace` - Optional The URL of the namespace definition - * @key `prefix` - Optional The prefix to be used for the name - * @key `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element - * @key `wrapped` - Optional MAY be used only for an array definition - * @key `x-${string}` - Specification Extensions - * - * @note - * All fields are optional. - * - * ----- - * Examples - * ----- - * - * @example (simple XML): - * ```ts - * const xml: XML = { - * name: "animal" - * }; - * ``` - */ -export interface XML extends Extension { - /** - * Replaces the name of the element/attribute used for the described schema property. - * When defined within items, it will affect the name of the individual XML elements within the list. - * When defined alongside type being array (outside the items), it will affect the wrapping element - * and only if wrapped is true. If wrapped is false, it will affect the items within the array. - * - * @example "animal" - * @example "item" - */ - name?: string - - /** - * The URL of the namespace definition. Value SHOULD be in the form of a URL. - * - * @example "http://example.com/schema" - * @example "http://www.w3.org/XML/1998/namespace" - */ - namespace?: string - - /** - * The prefix to be used for the name. - * - * @example "xs" - * @example "ns" - */ - prefix?: string - - /** - * Declares whether the property definition translates to an attribute instead of an element. - * Default value is false. - * - * @example true - * @example false - */ - attribute?: boolean - - /** - * MAY be used only for an array definition. Signifies whether the array is wrapped (for example, - * ) or unwrapped (). Default value is false. - * The definition takes effect only when defined alongside type being array (outside the items). - * - * @example true - * @example false - */ - wrapped?: boolean -} diff --git a/3.0.x/3.0.0.md b/3.0/3.0.0.md similarity index 100% rename from 3.0.x/3.0.0.md rename to 3.0/3.0.0.md diff --git a/3.0.x/3.0.1.md b/3.0/3.0.1.md similarity index 100% rename from 3.0.x/3.0.1.md rename to 3.0/3.0.1.md diff --git a/3.0.x/3.0.2.md b/3.0/3.0.2.md similarity index 100% rename from 3.0.x/3.0.2.md rename to 3.0/3.0.2.md diff --git a/3.0.x/3.0.3.md b/3.0/3.0.3.md similarity index 100% rename from 3.0.x/3.0.3.md rename to 3.0/3.0.3.md diff --git a/3.0.x/3.0.4.md b/3.0/3.0.4.md similarity index 100% rename from 3.0.x/3.0.4.md rename to 3.0/3.0.4.md diff --git a/3.0/components.ts b/3.0/components.ts new file mode 100644 index 0000000..9a7ae87 --- /dev/null +++ b/3.0/components.ts @@ -0,0 +1,214 @@ +import type { Extension } from "./extensions"; +import type { + Callback, + Example, + Header, + Link, + Parameter, + RequestBody, + Response, +} from "./paths"; +import type { Reference } from "./references"; +import type { Schema } from "./schema"; +import type { SecurityScheme } from "./security"; + +/** + * ----- + * Components Object + * ----- + * + * Holds a set of reusable objects for different aspects of the OAS. All objects defined + * within the components object will have no effect on the API unless they are explicitly + * referenced from properties outside the components object. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object} | + * + * ----- + * Fields + * ----- + * + * @property `schemas` - An object to hold reusable Schema Objects + * @property `responses` - An object to hold reusable Response Objects + * @property `parameters` - An object to hold reusable Parameter Objects + * @property `examples` - An object to hold reusable Example Objects + * @property `requestBodies` - An object to hold reusable Request Body Objects + * @property `headers` - An object to hold reusable Header Objects + * @property `securitySchemes` - An object to hold reusable Security Scheme Objects + * @property `links` - An object to hold reusable Link Objects + * @property `callbacks` - An object to hold reusable Callback Objects + * @property `x-${string}` - Specification Extensions + * + * @note + * All objects defined within the components object will have no effect on the API unless + * they are explicitly referenced from properties outside the components object. + * + * ----- + * Examples + * ----- + * + * @example (basic components): + * ```ts + * const components: Components = { + * schemas: { + * User: { + * type: "object", + * properties: { + * id: { type: "integer" }, + * name: { type: "string" } + * } + * } + * } + * }; + * ``` + */ +export interface Components extends Extension { + /** + * An object to hold reusable Schema Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - schemas} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - schemas} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - schemas} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - schemas} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - schemas} | + * @property `schemas` - Optional An object to hold reusable Schema Objects + * + * @example { "User": { type: "object", properties: { id: { type: "integer" } } } } + */ + schemas?: Record; + + /** + * An object to hold reusable Response Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - responses} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - responses} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - responses} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - responses} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - responses} | + * @property `responses` - Optional An object to hold reusable Response Objects + * + * @example { "NotFound": { description: "Resource not found" } } + */ + responses?: Record; + + /** + * An object to hold reusable Parameter Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - parameters} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - parameters} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - parameters} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - parameters} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - parameters} | + * @property `parameters` - Optional An object to hold reusable Parameter Objects + * + * @example { "LimitParam": { name: "limit", in: "query", schema: { type: "integer" } } } + */ + parameters?: Record; + + /** + * An object to hold reusable Example Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - examples} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - examples} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - examples} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - examples} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - examples} | + * @property `examples` - Optional An object to hold reusable Example Objects + * + * @example { "UserExample": { summary: "A user example", value: { id: 1, name: "John" } } } + */ + examples?: Record; + + /** + * An object to hold reusable Request Body Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - requestBodies} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - requestBodies} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - requestBodies} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - requestBodies} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - requestBodies} | + * @property `requestBodies` - Optional An object to hold reusable Request Body Objects + * + * @example { "UserRequest": { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } } + */ + requestBodies?: Record; + + /** + * An object to hold reusable Header Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - headers} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - headers} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - headers} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - headers} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - headers} | + * @property `headers` - Optional An object to hold reusable Header Objects + * + * @example { "RateLimit": { description: "Rate limit header", schema: { type: "integer" } } } + */ + headers?: Record; + + /** + * An object to hold reusable Security Scheme Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - securitySchemes} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - securitySchemes} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - securitySchemes} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - securitySchemes} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - securitySchemes} | + * @property `securitySchemes` - Optional An object to hold reusable Security Scheme Objects + * + * @example { "ApiKeyAuth": { type: "apiKey", in: "header", name: "X-API-Key" } } + */ + securitySchemes?: Record; + + /** + * An object to hold reusable Link Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - links} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - links} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - links} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - links} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - links} | + * @property `links` - Optional An object to hold reusable Link Objects + * + * @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } } + */ + links?: Record; + + /** + * An object to hold reusable Callback Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - callbacks} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - callbacks} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - callbacks} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - callbacks} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - callbacks} | + * @property `callbacks` - Optional An object to hold reusable Callback Objects + * + * @example { "MyCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { $ref: "#/components/requestBodies/SomeRequestBody" } } } } } + */ + callbacks?: Record; +} diff --git a/3.0/data-types/array.ts b/3.0/data-types/array.ts new file mode 100644 index 0000000..69687bd --- /dev/null +++ b/3.0/data-types/array.ts @@ -0,0 +1,209 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { Schema } from "../schema"; +import type { XML } from "../xml"; + +/** + * ----- + * Array Schema + * ----- + * + * A schema for array data types with array-specific validation constraints. + * Only valid with `type: "array"` and includes array properties like + * `items`, `maxItems`, `minItems`, and `uniqueItems`. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "array" + * @property `items` - Schema for the items in the array + * @property `maxItems` - Maximum number of items in the array + * @property `minItems` - Minimum number of items in the array + * @property `uniqueItems` - Whether all items must be unique + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid array values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `x-${string}` - Specification Extensions + * + * @note + * Array-specific constraints (`items`, `maxItems`, `minItems`, `uniqueItems`) are only + * valid with `type: "array"`. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (basic array): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" }, + * description: "Array of strings" + * }; + * ``` + * + * @example (array with validation): + * ```ts + * const tagsSchema: ArraySchema = { + * type: "array", + * items: { type: "string" }, + * minItems: 1, + * maxItems: 10, + * uniqueItems: true, + * description: "Array of unique tags" + * }; + * ``` + * + * @example (array of objects): + * ```ts + * const usersSchema: ArraySchema = { + * type: "array", + * items: { $ref: "#/components/schemas/User" }, + * description: "Array of user objects" + * }; + * ``` + * + * @example (array with enum): + * ```ts + * const statusesSchema: ArraySchema = { + * type: "array", + * items: { type: "string", enum: ["active", "inactive"] }, + * description: "Array of status values" + * }; + * ``` + */ +export interface ArraySchema extends Extension { + /** + * The type of the schema. Must be "array" for array schemas. + * + * @example "array" + */ + type: "array"; + + /** + * A short title for the schema. + * + * @example "Tags" + * @example "User List" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "Array of tag strings" + * @example "List of user objects" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example ["tag1", "tag2"] + * @example [] + */ + default?: unknown[]; + + /** + * Example value for the schema. + * + * @example ["example1", "example2"] + * @example [1, 2, 3] + */ + example?: unknown[]; + + /** + * Enumeration of valid array values. + * + * @example [["a", "b"], ["c", "d"]] + * @example [[1, 2], [3, 4]] + */ + enum?: unknown[][]; + + /** + * Whether the property is read-only. Default value is false. + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * + * @example { name: "tags", wrapped: true } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * + * @example { description: "Find out more about this field", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * + * @default false + * @example true + */ + deprecated?: boolean; + + // Array-specific validation constraints + /** + * Schema for the items in the array. This field is required for array schemas. + * + * @example { type: "string" } + * @example { $ref: "#/components/schemas/User" } + */ + items?: Schema; + + /** + * Maximum number of items in the array. The value MUST be a non-negative integer. + * + * @example 10 + * @example 100 + */ + maxItems?: number; + + /** + * Minimum number of items in the array. The value MUST be a non-negative integer. + * + * @example 1 + * @example 0 + */ + minItems?: number; + + /** + * Whether all items in the array must be unique. Default value is false. + * + * @default false + * @example true + */ + uniqueItems?: boolean; +} diff --git a/3.0/data-types/boolean.ts b/3.0/data-types/boolean.ts new file mode 100644 index 0000000..491c416 --- /dev/null +++ b/3.0/data-types/boolean.ts @@ -0,0 +1,167 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { XML } from "../xml"; + +/** + * ----- + * Boolean Schema + * ----- + * + * A schema for boolean data types (true/false values) with basic validation. + * Only valid with `type: "boolean"` and includes common metadata properties + * but no boolean-specific validation constraints. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "boolean" + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid boolean values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `x-${string}` - Specification Extensions + * + * @note + * Boolean schemas have no type-specific validation constraints beyond + * the basic metadata properties. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (basic boolean): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * description: "A true/false value" + * }; + * ``` + * + * @example (boolean with default): + * ```ts + * const enabledSchema: BooleanSchema = { + * type: "boolean", + * default: false, + * description: "Whether the feature is enabled" + * }; + * ``` + * + * @example (boolean with enum): + * ```ts + * const statusSchema: BooleanSchema = { + * type: "boolean", + * enum: [true, false], + * default: false, + * description: "Active status" + * }; + * ``` + * + * @example (read-only boolean): + * ```ts + * const computedSchema: BooleanSchema = { + * type: "boolean", + * readOnly: true, + * description: "Computed value that cannot be set directly" + * }; + * ``` + */ +export interface BooleanSchema extends Extension { + /** + * The type of the schema. Must be "boolean" for boolean schemas. + * + * @example "boolean" + */ + type: "boolean"; + + /** + * A short title for the schema. + * + * @example "Is Active" + * @example "Enabled" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "Whether the user is active" + * @example "Feature enabled status" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example true + * @example false + */ + default?: boolean; + + /** + * Example value for the schema. + * + * @example true + * @example false + */ + example?: boolean; + + /** + * Enumeration of valid boolean values. + * + * @example [true, false] + */ + enum?: boolean[]; + + /** + * Whether the property is read-only. Default value is false. + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * + * @example { name: "isActive", attribute: true } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * + * @example { description: "Find out more about this field", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * + * @default false + * @example true + */ + deprecated?: boolean; +} diff --git a/3.0/data-types/composition.ts b/3.0/data-types/composition.ts new file mode 100644 index 0000000..77d6439 --- /dev/null +++ b/3.0/data-types/composition.ts @@ -0,0 +1,210 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { Discriminator, Schema } from "../schema"; +import type { XML } from "../xml"; + +/** + * ----- + * Composition Schema + * ----- + * + * A schema that uses composition keywords (allOf, anyOf, oneOf, not) for schema + * composition and logical operations. These keywords are mutually exclusive with + * `$ref` but can appear with any validation keywords. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `allOf` - Array of schemas that must all be valid + * @property `anyOf` - Array of schemas where at least one must be valid + * @property `oneOf` - Array of schemas where exactly one must be valid + * @property `not` - Schema that must not be valid + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `discriminator` - Discriminator for polymorphism + * @property `x-${string}` - Specification Extensions + * + * @note + * Composition keywords are mutually exclusive with `$ref` but can appear with + * any validation keywords. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (allOf composition): + * ```ts + * const composedSchema: CompositionSchema = { + * allOf: [ + * { $ref: "#/components/schemas/BaseUser" }, + * { type: "object", required: ["id"] } + * ], + * description: "User with base properties plus required id" + * }; + * ``` + * + * @example (anyOf composition): + * ```ts + * const flexibleSchema: CompositionSchema = { + * anyOf: [ + * { type: "string" }, + * { type: "integer" } + * ], + * description: "String or integer value" + * }; + * ``` + * + * @example (oneOf composition): + * ```ts + * const choiceSchema: CompositionSchema = { + * oneOf: [ + * { $ref: "#/components/schemas/Dog" }, + * { $ref: "#/components/schemas/Cat" } + * ], + * discriminator: "petType", + * description: "Either a dog or cat" + * }; + * ``` + * + * @example (not composition): + * ```ts + * const exclusionSchema: CompositionSchema = { + * not: { type: "null" }, + * description: "Any value except null" + * }; + * ``` + */ +export interface CompositionSchema extends Extension { + /** + * A short title for the schema. + * + * @example "Composed User" + * @example "Flexible Value" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "Schema composed from multiple base schemas" + * @example "Value that can be string or number" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example "default value" + * @example { name: "default" } + */ + default?: unknown; + + /** + * Example value for the schema. + * + * @example "example value" + * @example { name: "example" } + */ + example?: unknown; + + /** + * Enumeration of valid values. + * + * @example ["value1", "value2"] + * @example [1, 2, 3] + */ + enum?: unknown[]; + + /** + * Whether the property is read-only. Default value is false. + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * + * @example { name: "composed", wrapped: true } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * + * @example { description: "Find out more about this schema", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * + * @default false + * @example true + */ + deprecated?: boolean; + + /** + * Discriminator for polymorphism. The property name used to differentiate between schemas. + * + * @example "petType" + * @example "type" + */ + discriminator?: Discriminator; + + // Composition keywords (mutually exclusive) + /** + * Array of schemas that must all be valid for the instance to be valid. + * + * @example [{ $ref: "#/components/schemas/Base" }, { type: "object", required: ["id"] }] + */ + allOf?: Schema[]; + + /** + * Array of schemas where at least one must be valid for the instance to be valid. + * + * @example [{ type: "string" }, { type: "integer" }] + */ + anyOf?: Schema[]; + + /** + * Array of schemas where exactly one must be valid for the instance to be valid. + * + * @example [{ $ref: "#/components/schemas/Dog" }, { $ref: "#/components/schemas/Cat" }] + */ + oneOf?: Schema[]; + + /** + * Schema that must not be valid for the instance to be valid. + * + * @example { type: "null" } + * @example { type: "string", maxLength: 0 } + */ + not?: Schema; +} diff --git a/3.0/data-types/index.ts b/3.0/data-types/index.ts new file mode 100644 index 0000000..2058543 --- /dev/null +++ b/3.0/data-types/index.ts @@ -0,0 +1,10 @@ +// Individual schema types + +export type { ArraySchema } from "./array"; +export type { BooleanSchema } from "./boolean"; +export type { CompositionSchema } from "./composition"; +export type { IntegerSchema } from "./integer"; +export type { NumberSchema } from "./number"; +export type { ObjectSchema } from "./object"; +export type { ReferenceSchema } from "./reference"; +export type { StringSchema } from "./string"; diff --git a/3.0/data-types/integer.ts b/3.0/data-types/integer.ts new file mode 100644 index 0000000..52ca0be --- /dev/null +++ b/3.0/data-types/integer.ts @@ -0,0 +1,225 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { XML } from "../xml"; + +/** + * ----- + * Integer Schema + * ----- + * + * A schema for integer data types (whole numbers) with integer-specific + * validation constraints. Only valid with `type: "integer"` and includes + * numeric properties like `multipleOf`, `maximum`, `minimum`, etc. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "integer" + * @property `format` - The extending format for the integer type + * @property `multipleOf` - Number must be a multiple of this value + * @property `maximum` - Maximum value (inclusive) + * @property `exclusiveMaximum` - Maximum value (exclusive) + * @property `minimum` - Minimum value (inclusive) + * @property `exclusiveMinimum` - Minimum value (exclusive) + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid integer values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `x-${string}` - Specification Extensions + * + * @note + * Integer-specific constraints (`multipleOf`, `maximum`, `minimum`, etc.) are only + * valid with `type: "integer"`. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (basic integer): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * description: "A whole number" + * }; + * ``` + * + * @example (integer with format): + * ```ts + * const int32Schema: IntegerSchema = { + * type: "integer", + * format: "int32", + * description: "32-bit signed integer" + * }; + * ``` + * + * @example (integer with validation): + * ```ts + * const ageSchema: IntegerSchema = { + * type: "integer", + * minimum: 0, + * maximum: 150, + * description: "Person's age in years" + * }; + * ``` + * + * @example (integer with enum): + * ```ts + * const statusCodeSchema: IntegerSchema = { + * type: "integer", + * enum: [200, 201, 400, 401, 404, 500], + * description: "HTTP status code" + * }; + * ``` + */ +export interface IntegerSchema extends Extension { + /** + * The type of the schema. Must be "integer" for integer schemas. + * + * @example "integer" + */ + type: "integer"; + + /** + * The extending format for the integer type. See OpenAPI 3.0.x Data Type Formats for details. + * + * @example "int32" + * @example "int64" + */ + format?: string; + + /** + * A short title for the schema. + * + * @example "User ID" + * @example "Age" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "The user's unique identifier" + * @example "Age in years" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example 0 + * @example 1 + */ + default?: number; + + /** + * Example value for the schema. + * + * @example 42 + * @example 100 + */ + example?: number; + + /** + * Enumeration of valid integer values. + * + * @example [1, 2, 3, 4, 5] + * @example [0, 1, 2] + */ + enum?: number[]; + + /** + * Whether the property is read-only. Default value is false. + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * + * @example { name: "userId", attribute: true } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * + * @example { description: "Find out more about this field", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * + * @default false + * @example true + */ + deprecated?: boolean; + + // Integer-specific validation constraints + /** + * A number is valid against "multipleOf" if the result of the division + * of the instance by this keyword's value is an integer. + * + * @example 1 + * @example 2 + * @example 5 + */ + multipleOf?: number; + + /** + * A number is valid against "maximum" if it is less than or equal to this value. + * + * @example 100 + * @example 2147483647 + */ + maximum?: number; + + /** + * A number is valid against "exclusiveMaximum" if it is strictly less than this value. + * + * @example 100 + * @example 1000 + */ + exclusiveMaximum?: number; + + /** + * A number is valid against "minimum" if it is greater than or equal to this value. + * + * @example 0 + * @example 1 + */ + minimum?: number; + + /** + * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. + * + * @example 0 + * @example -1 + */ + exclusiveMinimum?: number; +} diff --git a/3.0/data-types/number.ts b/3.0/data-types/number.ts new file mode 100644 index 0000000..5e9382e --- /dev/null +++ b/3.0/data-types/number.ts @@ -0,0 +1,227 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { XML } from "../xml"; + +/** + * ----- + * Number Schema + * ----- + * + * A schema for numeric data types (floating-point numbers) with numeric-specific + * validation constraints. Only valid with `type: "number"` and includes numeric + * properties like `multipleOf`, `maximum`, `minimum`, etc. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "number" + * @property `format` - The extending format for the number type + * @property `multipleOf` - Number must be a multiple of this value + * @property `maximum` - Maximum value (inclusive) + * @property `exclusiveMaximum` - Maximum value (exclusive) + * @property `minimum` - Minimum value (inclusive) + * @property `exclusiveMinimum` - Minimum value (exclusive) + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid number values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `x-${string}` - Specification Extensions + * + * @note + * Numeric constraints (`multipleOf`, `maximum`, `minimum`, etc.) are only + * valid with `type: "number"` or `type: "integer"`. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (basic number): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * description: "A floating-point number" + * }; + * ``` + * + * @example (number with format): + * ```ts + * const floatSchema: NumberSchema = { + * type: "number", + * format: "float", + * description: "Single precision floating-point number" + * }; + * ``` + * + * @example (number with validation): + * ```ts + * const priceSchema: NumberSchema = { + * type: "number", + * minimum: 0, + * maximum: 999.99, + * multipleOf: 0.01, + * description: "Price in dollars with cent precision" + * }; + * ``` + * + * @example (number with enum): + * ```ts + * const ratingSchema: NumberSchema = { + * type: "number", + * enum: [1.0, 2.0, 3.0, 4.0, 5.0], + * default: 3.0, + * description: "Product rating from 1 to 5" + * }; + * ``` + */ +export interface NumberSchema extends Extension { + /** + * The type of the schema. Must be "number" for number schemas. + * + * @example "number" + */ + type: "number"; + + /** + * The extending format for the number type. See OpenAPI 3.0.x Data Type Formats for details. + * + * @example "float" + * @example "double" + */ + format?: string; + + /** + * A short title for the schema. + * + * @example "Price" + * @example "Temperature" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "The price in dollars" + * @example "Temperature in Celsius" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example 0 + * @example 25.5 + */ + default?: number; + + /** + * Example value for the schema. + * + * @example 19.99 + * @example 98.6 + */ + example?: number; + + /** + * Enumeration of valid number values. + * + * @example [1.0, 2.0, 3.0, 4.0, 5.0] + * @example [0.0, 0.5, 1.0] + */ + enum?: number[]; + + /** + * Whether the property is read-only. Default value is false. + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * + * @example { name: "price", attribute: true } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * + * @example { description: "Find out more about this field", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * + * @default false + * @example true + */ + deprecated?: boolean; + + // Number-specific validation constraints + /** + * A number is valid against "multipleOf" if the result of the division + * of the instance by this keyword's value is an integer. + * + * @example 0.01 + * @example 0.1 + * @example 2 + */ + multipleOf?: number; + + /** + * A number is valid against "maximum" if it is less than or equal to this value. + * + * @example 100 + * @example 999.99 + */ + maximum?: number; + + /** + * A number is valid against "exclusiveMaximum" if it is strictly less than this value. + * + * @example 100 + * @example 1000 + */ + exclusiveMaximum?: number; + + /** + * A number is valid against "minimum" if it is greater than or equal to this value. + * + * @example 0 + * @example -273.15 + */ + minimum?: number; + + /** + * A number is valid against "exclusiveMinimum" if it is strictly greater than this value. + * + * @example 0 + * @example -100 + */ + exclusiveMinimum?: number; +} diff --git a/3.0/data-types/object.ts b/3.0/data-types/object.ts new file mode 100644 index 0000000..6e3594e --- /dev/null +++ b/3.0/data-types/object.ts @@ -0,0 +1,259 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { Discriminator, Schema } from "../schema"; +import type { XML } from "../xml"; + +/** + * ----- + * Object Schema + * ----- + * + * A schema for object data types with object-specific validation constraints. + * Only valid with `type: "object"` and includes object properties like + * `properties`, `required`, `additionalProperties`, etc. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "object" + * @property `properties` - Properties of the object + * @property `required` - Required property names + * @property `additionalProperties` - Additional properties schema + * @property `patternProperties` - Pattern-based properties + * @property `propertyNames` - Schema for property names + * @property `maxProperties` - Maximum number of properties + * @property `minProperties` - Minimum number of properties + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid object values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `discriminator` - Discriminator for polymorphism + * @property `x-${string}` - Specification Extensions + * + * @note + * Object-specific constraints (`properties`, `required`, `additionalProperties`, etc.) are only + * valid with `type: "object"`. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (basic object): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "integer" } + * }, + * description: "A person object" + * }; + * ``` + * + * @example (object with required properties): + * ```ts + * const userSchema: ObjectSchema = { + * type: "object", + * properties: { + * id: { type: "integer" }, + * name: { type: "string" }, + * email: { type: "string", format: "email" } + * }, + * required: ["id", "name", "email"], + * description: "User object with required fields" + * }; + * ``` + * + * @example (object with additional properties): + * ```ts + * const flexibleSchema: ObjectSchema = { + * type: "object", + * properties: { + * id: { type: "integer" } + * }, + * additionalProperties: { type: "string" }, + * description: "Object allowing additional string properties" + * }; + * ``` + * + * @example (object with discriminator): + * ```ts + * const petSchema: ObjectSchema = { + * type: "object", + * discriminator: "petType", + * properties: { + * name: { type: "string" }, + * petType: { type: "string" } + * }, + * required: ["name", "petType"], + * description: "Base pet object with discriminator" + * }; + * ``` + */ +export interface ObjectSchema extends Extension { + /** + * The type of the schema. Must be "object" for object schemas. + * + * @example "object" + */ + type: "object"; + + /** + * A short title for the schema. + * + * @example "User" + * @example "Product" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "A user object containing basic information" + * @example "Product information with pricing" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example { name: "John", age: 30 } + * @example {} + */ + default?: Record; + + /** + * Example value for the schema. + * + * @example { name: "Jane", age: 25 } + * @example { id: 1, title: "Sample" } + */ + example?: Record; + + /** + * Enumeration of valid object values. + * + * @example [{ name: "John" }, { name: "Jane" }] + * @example [{ status: "active" }, { status: "inactive" }] + */ + enum?: Record[]; + + /** + * Whether the property is read-only. Default value is false. + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * + * @example { name: "user", wrapped: false } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * + * @example { description: "Find out more about this object", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * + * @default false + * @example true + */ + deprecated?: boolean; + + /** + * Discriminator for polymorphism. The property name used to differentiate between schemas. + * + * @example "petType" + * @example "type" + */ + discriminator?: Discriminator; + + // Object-specific validation constraints + /** + * Properties of the object. Each property name maps to a schema definition. + * + * @example { name: { type: "string" }, age: { type: "integer" } } + * @example { id: { $ref: "#/components/schemas/Id" } } + */ + properties?: Record; + + /** + * Array of property names that are required. Properties not listed here are optional. + * + * @example ["id", "name"] + * @example ["email"] + */ + required?: string[]; + + /** + * Schema for additional properties not defined in the properties object. + * Can be a boolean or a schema. + * + * @example true + * @example false + * @example { type: "string" } + */ + additionalProperties?: boolean | Schema; + + /** + * Pattern-based properties using regular expressions as keys. + * + * @example { "^S_": { type: "string" } } + * @example { "^[0-9]+$": { type: "integer" } } + */ + patternProperties?: Record; + + /** + * Schema for property names. If present, property names must conform to this schema. + * + * @example { type: "string", pattern: "^[a-zA-Z][a-zA-Z0-9]*$" } + */ + propertyNames?: Schema; + + /** + * Maximum number of properties in the object. The value MUST be a non-negative integer. + * + * @example 10 + * @example 50 + */ + maxProperties?: number; + + /** + * Minimum number of properties in the object. The value MUST be a non-negative integer. + * + * @example 1 + * @example 2 + */ + minProperties?: number; +} diff --git a/3.0.x/data-types/reference.ts b/3.0/data-types/reference.ts similarity index 71% rename from 3.0.x/data-types/reference.ts rename to 3.0/data-types/reference.ts index b8f41f9..8777a95 100644 --- a/3.0.x/data-types/reference.ts +++ b/3.0/data-types/reference.ts @@ -1,4 +1,4 @@ -import type { Extension } from "../extensions" +import type { Extension } from "../extensions"; /** * ----- @@ -24,9 +24,9 @@ import type { Extension } from "../extensions" * Fields * ----- * - * @key `$ref` - The reference string. MUST be a valid JSON Reference. - * @key `description` - A short description of the referenced schema. - * @key `x-${string}` - Specification Extensions + * @property `$ref` - The reference string. MUST be a valid JSON Reference. + * @property `description` - A short description of the referenced schema. + * @property `x-${string}` - Specification Extensions * * @note * When using `$ref`, no other schema properties are allowed except @@ -61,20 +61,20 @@ import type { Extension } from "../extensions" * ``` */ export interface ReferenceSchema extends Extension { - /** - * The reference string. MUST be a valid JSON Reference. - * - * @example "#/components/schemas/User" - * @example "#/components/responses/NotFound" - * @example "#/components/parameters/LimitParam" - */ - $ref: string + /** + * The reference string. MUST be a valid JSON Reference. + * + * @example "#/components/schemas/User" + * @example "#/components/responses/NotFound" + * @example "#/components/parameters/LimitParam" + */ + $ref: string; - /** - * A short description of the referenced schema. CommonMark syntax MAY be used for rich text representation. - * - * @example "A reference to the User schema" - * @example "Pet object definition" - */ - description?: string + /** + * A short description of the referenced schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "A reference to the User schema" + * @example "Pet object definition" + */ + description?: string; } diff --git a/3.0/data-types/string.ts b/3.0/data-types/string.ts new file mode 100644 index 0000000..13a483b --- /dev/null +++ b/3.0/data-types/string.ts @@ -0,0 +1,344 @@ +import type { Extension } from "../extensions"; +import type { ExternalDocumentation } from "../externalDocs"; +import type { XML } from "../xml"; + +/** + * ----- + * String Schema + * ----- + * + * A schema for string data types with string-specific validation constraints. + * Only valid with `type: "string"` and includes string-specific properties + * like `maxLength`, `minLength`, and `pattern`. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Must be "string" + * @property `format` - The extending format for the string type + * @property `maxLength` - Maximum length of the string + * @property `minLength` - Minimum length of the string + * @property `pattern` - Regular expression pattern the string must match + * @property `title` - A short title for the schema + * @property `description` - A short description of the schema + * @property `default` - Default value for the schema + * @property `example` - Example value for the schema + * @property `enum` - Enumeration of valid string values + * @property `readOnly` - Whether the property is read-only + * @property `writeOnly` - Whether the property is write-only + * @property `xml` - XML representation metadata + * @property `externalDocs` - Additional external documentation + * @property `deprecated` - Whether the schema is deprecated + * @property `x-${string}` - Specification Extensions + * + * @note + * String-specific constraints (`maxLength`, `minLength`, `pattern`) are only + * valid with `type: "string"`. This is enforced by the type system. + * + * ----- + * Examples + * ----- + * + * @example (basic string): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * description: "A simple string field" + * }; + * ``` + * + * @example (string with format): + * ```ts + * const emailSchema: StringSchema = { + * type: "string", + * format: "email", + * description: "Email address" + * }; + * ``` + * + * @example (string with validation): + * ```ts + * const passwordSchema: StringSchema = { + * type: "string", + * minLength: 8, + * maxLength: 128, + * pattern: "^[a-zA-Z0-9!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>\\/?]+$", + * description: "Password with length and character requirements" + * }; + * ``` + * + * @example (string with enum): + * ```ts + * const statusSchema: StringSchema = { + * type: "string", + * enum: ["active", "inactive", "pending"], + * default: "pending", + * description: "User status" + * }; + * ``` + */ +export interface StringSchema extends Extension { + /** + * The type of the schema. Must be "string" for string schemas. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - type} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - type} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - type} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - type} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - type} | + * @property `type` - Required The type of the schema + * + * @example "string" + */ + type: "string"; + + /** + * The extending format for the string type. See OpenAPI 3.0.x Data Type Formats for details. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - format} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - format} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - format} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - format} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - format} | + * @property `format` - Optional The extending format for the string type + * + * @example "email" + * @example "date" + * @example "uuid" + * @example "uri" + */ + format?: string; + + /** + * A short title for the schema. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - title} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - title} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - title} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - title} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - title} | + * @property `title` - Optional A short title for the schema + * + * @example "User Name" + * @example "Email Address" + */ + title?: string; + + /** + * A short description of the schema. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - description} | + * @property `description` - Optional A short description of the schema + * + * @example "The user's full name" + * @example "Email address in RFC 5322 format" + */ + description?: string; + + /** + * The default value for the schema. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - default} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - default} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - default} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - default} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - default} | + * @property `default` - Optional The default value for the schema + * + * @example "John Doe" + * @example "user@example.com" + */ + default?: string; + + /** + * Example value for the schema. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - example} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - example} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - example} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - example} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - example} | + * @property `example` - Optional Example value for the schema + * + * @example "Jane Smith" + * @example "admin@example.com" + */ + example?: string; + + /** + * Enumeration of valid string values. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - enum} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - enum} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - enum} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - enum} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - enum} | + * @property `enum` - Optional Enumeration of valid string values + * + * @example ["active", "inactive", "pending"] + * @example ["red", "green", "blue"] + */ + enum?: string[]; + + /** + * Whether the property is read-only. Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - readOnly} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - readOnly} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - readOnly} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - readOnly} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - readOnly} | + * @property `readOnly` - Optional Whether the property is read-only + * + * @default false + * @example true + */ + readOnly?: boolean; + + /** + * Whether the property is write-only. Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - writeOnly} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - writeOnly} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - writeOnly} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - writeOnly} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - writeOnly} | + * @property `writeOnly` - Optional Whether the property is write-only + * + * @default false + * @example true + */ + writeOnly?: boolean; + + /** + * XML representation metadata for the schema. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - xml} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - xml} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - xml} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - xml} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - xml} | + * @property `xml` - Optional XML representation metadata for the schema + * + * @example { name: "userName", attribute: false } + */ + xml?: XML; + + /** + * Additional external documentation for the schema. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - externalDocs} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - externalDocs} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - externalDocs} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - externalDocs} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - externalDocs} | + * @property `externalDocs` - Optional Additional external documentation for the schema + * + * @example { description: "Find out more about this field", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Whether the schema is deprecated. Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - deprecated} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - deprecated} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - deprecated} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - deprecated} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - deprecated} | + * @property `deprecated` - Optional Whether the schema is deprecated + * + * @default false + * @example true + */ + deprecated?: boolean; + + // String-specific validation constraints + /** + * Maximum length of the string. The value MUST be a non-negative integer. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - maxLength} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - maxLength} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - maxLength} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - maxLength} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - maxLength} | + * @property `maxLength` - Optional Maximum length of the string + * + * @example 100 + * @example 255 + */ + maxLength?: number; + + /** + * Minimum length of the string. The value MUST be a non-negative integer. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - minLength} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - minLength} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - minLength} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - minLength} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - minLength} | + * @property `minLength` - Optional Minimum length of the string + * + * @example 1 + * @example 8 + */ + minLength?: number; + + /** + * Regular expression pattern the string must match. The pattern MUST be a valid regular expression. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object - pattern} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object - pattern} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object - pattern} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object - pattern} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object - pattern} | + * @property `pattern` - Optional Regular expression pattern the string must match + * + * @example "^[a-zA-Z0-9]+$" + * @example "^\\d{4}-\\d{2}-\\d{2}$" + */ + pattern?: string; +} diff --git a/3.0.x/extensions.ts b/3.0/extensions.ts similarity index 93% rename from 3.0.x/extensions.ts rename to 3.0/extensions.ts index c7b3294..9eb4114 100644 --- a/3.0.x/extensions.ts +++ b/3.0/extensions.ts @@ -19,7 +19,7 @@ * Fields * ----- * - * @key `x-${string}` - Specification Extensions + * @property `x-${string}` - Specification Extensions * * @note * All extension property names MUST begin with "x-". @@ -43,5 +43,5 @@ * ``` */ export type Extension = { - [K in `x-${string}`]: unknown -} + [K in `x-${string}`]: unknown; +}; diff --git a/3.0/externalDocs.ts b/3.0/externalDocs.ts new file mode 100644 index 0000000..e721ba3 --- /dev/null +++ b/3.0/externalDocs.ts @@ -0,0 +1,75 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * External Documentation Object + * ----- + * + * Allows referencing an external resource for extended documentation. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A short description of the target documentation + * @property `url` - Required The URL for the target documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `url` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple external docs): + * ```ts + * const externalDocs: ExternalDocumentation = { + * description: "Find more info here", + * url: "https://example.com/docs" + * }; + * ``` + */ +export interface ExternalDocumentation extends Extension { + /** + * A short description of the target documentation. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation Object - description} | + * @property `description` - Optional A short description of the target documentation + * + * @example "Find more info here" + * @example "Additional documentation for this API" + */ + description?: string; + + /** + * The URL for the target documentation. MUST be in the format of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation Object - url} | + * @property `url` - Required The URL for the target documentation + * + * @example "https://example.com/docs" + * @example "https://api.example.com/documentation" + */ + url: string; +} diff --git a/3.0/index.ts b/3.0/index.ts new file mode 100644 index 0000000..46cfd36 --- /dev/null +++ b/3.0/index.ts @@ -0,0 +1,65 @@ +// Centralized exports for OpenAPI 3.0 types +// This file serves as the main entry point for all OpenAPI 3.0 type definitions + +export type { + // Components types + Components, +} from "./components"; + +// Re-export all types for convenience +export type { + // Core types + Extension, +} from "./extensions"; +export type { ExternalDocumentation } from "./externalDocs"; +export type { + Contact, + // Info types + Info, + License, +} from "./info"; + +export type { + Callback, + Encoding, + Example, + Header, + Link, + MediaType, + Operation, + Parameter, + PathItemObject, + // Path types + Paths, + RequestBody, + Response, +} from "./paths"; +export type { Reference } from "./references"; + +export type { + Discriminator, + // Schema types + Schema, +} from "./schema"; +export type { + OAuthFlow, + OAuthFlows, + SecurityRequirement, + // Security types + SecurityScheme, +} from "./security"; +export type { + // Server types + Server, + ServerVariable, +} from "./servers"; +// Export the main specification type +export type { Specification } from "./spec"; +export type { + // Utility types + Tag, +} from "./tags"; +export type { + // XML types + XML, +} from "./xml"; diff --git a/3.0/info.ts b/3.0/info.ts new file mode 100644 index 0000000..c0c0669 --- /dev/null +++ b/3.0/info.ts @@ -0,0 +1,575 @@ +import type { LicenseName, LicenseURL } from "../License"; +import type { Extension } from "./extensions"; + +/** + * ----- + * Info Object + * ----- + * + * The object provides metadata about the API. + * The metadata MAY be used by the clients if needed, and MAY be presented in + * editing or documentation generation tools for convenience. + * + * The Info Object provides metadata about the API. This metadata can be used by + * clients if needed, and can be presented in the OpenAPI-UI for convenience. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info} | + * + * ----- + * Fields + * ----- + * + * @property `title` - Required The title of the application + * @property `description` - Optional A short description of the application + * @property `termsOfService` - Optional A URL to the Terms of Service for the API + * @property `contact` - Optional The contact information for the exposed API + * @property `license` - Optional The license information for the exposed API + * @property `version` - Required The version of the OpenAPI document + * @property `x-${string}` - Specification Extensions + * + * @note + * The `title` and `version` fields are required. In OpenAPI 3.0.1+, the `description` + * field was clarified to support CommonMark syntax for rich text representation. + * The `termsOfService` field must be a valid URL format. + * + * ----- + * Examples + * ----- + * + * @example (minimal info): + * ```ts + * const info: Info = { + * title: "Sample Pet Store App", + * version: "1.0.1" + * }; + * ``` + * + * @example (full info object): + * ```ts + * const info: Info = { + * title: "Sample Pet Store App", + * description: "This is a sample server for a pet store.", + * termsOfService: "http://example.com/terms/", + * contact: { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }, + * license: { + * name: "Apache 2.0", + * url: "http://www.apache.org/licenses/LICENSE-2.0.html" + * }, + * version: "1.0.1" + * }; + * ``` + */ +export interface Info extends Extension { + /** + * The title of the application. This field is required. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - title} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - title} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - title} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - title} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - title} | + * + * @property `title` - Required The title of the application + * + * @example "Sample Pet Store App" + * @example "My API" + */ + title: string; + + /** + * A short description of the application. CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - description} | + * + * @property `description` - Optional A short description of the application + * + * @example "This is a sample server for a pet store." + * @example "A comprehensive API for managing user data" + */ + description?: string; + + /** + * A URL to the Terms of Service for the API. MUST be in the format of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - termsOfService} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - termsOfService} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - termsOfService} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - termsOfService} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - termsOfService} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - termsOfService} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - termsOfService} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - termsOfService} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - termsOfService} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - termsOfService} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - termsOfService} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - termsOfService} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - termsOfService} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - termsOfService} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - termsOfService} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - termsOfService} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - termsOfService} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - termsOfService} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - termsOfService} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - termsOfService} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - termsOfService} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - termsOfService} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - termsOfService} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - termsOfService} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - termsOfService} | + * @property `termsOfService` - Optional A URL to the Terms of Service for the API + * + * @example "http://example.com/terms/" + * @example "https://example.com/terms" + */ + termsOfService?: string; + + /** + * The contact information for the exposed API. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - contact} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - contact} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - contact} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - contact} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - contact} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - contact} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - contact} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - contact} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - contact} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - contact} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - contact} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - contact} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - contact} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - contact} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - contact} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - contact} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - contact} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - contact} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - contact} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - contact} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - contact} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - contact} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - contact} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - contact} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - contact} | + * @property `contact` - Optional The contact information for the exposed API + * + * @example { name: "API Support", email: "support@example.com" } + */ + contact?: Contact; + + /** + * The license information for the exposed API. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - license} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - license} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - license} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - license} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - license} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - license} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - license} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - license} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - license} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - license} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - license} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - license} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - license} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - license} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - license} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - license} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - license} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - license} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - license} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - license} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - license} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - license} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - license} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - license} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - license} | + * @property `license` - Optional The license information for the exposed API + * + * @example { name: "Apache 2.0", url: "http://www.apache.org/licenses/LICENSE-2.0.html" } + */ + license?: License; + + /** + * The version of the OpenAPI document (which is distinct from the OpenAPI Specification version + * or the API implementation version). This field is required. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - version} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - version} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - version} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - version} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#info-object | OpenAPI 3.0.4 Info Object - version} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - version} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - version} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - version} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - version} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#info-object | OpenAPI 3.0.3 Info Object - version} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - version} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - version} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - version} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - version} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#info-object | OpenAPI 3.0.2 Info Object - version} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - version} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - version} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - version} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - version} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#info-object | OpenAPI 3.0.1 Info Object - version} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - version} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - version} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - version} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - version} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#info-object | OpenAPI 3.0.0 Info Object - version} | + * @property `version` - Required The version of the OpenAPI document + * + * @example "1.0.1" + * @example "2.0.0" + */ + version: string; +} + +/** + * ----- + * Contact Object + * ----- + * + * Contact information for the exposed API. + * + * The Contact Object provides contact information for the exposed API. It can + * include the name, URL, and email address of the contact person or organization. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Optional The identifying name of the contact person/organization + * @property `url` - Optional A URL pointing to the contact information + * @property `email` - Optional The email address of the contact person/organization + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. In OpenAPI 3.0.1+, the `url` field was clarified to + * must be in the format of a URL, and the `email` field must be in the format + * of an email address. + * + * ----- + * Examples + * ----- + * + * @example (full contact object): + * ```ts + * const contact: Contact = { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }; + * ``` + * + * @example (just name + email): + * ```ts + * const contact: Contact = { + * name: "Jane Doe", + * email: "jane.doe@example.com" + * }; + * ``` + * + * @example (with extension): + * ```ts + * const contact: Contact = { + * name: "Internal API Team", + * email: "api-team@example.com", + * "x-slack": "#api-support" + * }; + * ``` + */ +export interface Contact extends Extension { + /** + * The identifying name of the contact person/organization. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - name} | + * @property `name` - Optional The identifying name of the contact person/organization + * + * @example "API Support" + * @example "John Doe" + */ + name?: string; + + /** + * The URL pointing to the contact information. MUST be in the format of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - url} | + * @property `url` - Optional A URL pointing to the contact information + * + * @example "http://www.example.com/support" + * @example "https://example.com/contact" + */ + url?: string; + + /** + * The email address of the contact person/organization. MUST be in the format of an email address. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - email} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - email} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - email} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - email} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#contact-object | OpenAPI 3.0.4 Contact Object - email} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - email} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - email} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - email} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - email} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#contact-object | OpenAPI 3.0.3 Contact Object - email} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - email} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - email} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - email} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - email} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#contact-object | OpenAPI 3.0.2 Contact Object - email} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - email} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - email} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - email} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - email} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#contact-object | OpenAPI 3.0.1 Contact Object - email} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - email} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - email} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - email} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - email} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#contact-object | OpenAPI 3.0.0 Contact Object - email} | + * @property `email` - Optional The email address of the contact person/organization + * + * @example "support@example.com" + * @example "contact@example.com" + */ + email?: string; +} + +/** + * ----- + * License Object + * ----- + * + * License information for the exposed API. + * + * The License Object provides license information for the exposed API. It can + * include the name of the license and optionally a URL to the license text. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The license name used for the API + * @property `url` - Optional A URL to the license used for the API + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` field is required. The `url` field is optional but recommended. + * In OpenAPI 3.0.1+, the `url` field was clarified to must be in the format + * of a URL when provided. + * + * ----- + * Examples + * ----- + * + * @example (MIT License): + * ```ts + * const license: License = { + * name: "MIT License", + * url: "https://opensource.org/license/mit/" + * }; + * ``` + * + * @example (Apache 2.0): + * ```ts + * const license: License = { + * name: "Apache 2.0", + * url: "http://www.apache.org/licenses/LICENSE-2.0.html" + * }; + * ``` + * + * @example (license without URL): + * ```ts + * const license: License = { + * name: "Proprietary License" + * }; + * ``` + * + * @example (with extension): + * ```ts + * const license: License = { + * name: "Custom License", + * url: "https://example.com/license", + * "x-license-version": "1.0" + * }; + * ``` + */ +export interface License extends Extension { + /** + * The license name used for the API. This field is required. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - name} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - name} | + * @property `name` - Required The license name used for the API + * + * @example "MIT License" + * @example "Apache 2.0" + * @example "Proprietary License" + */ + name: LicenseName; + + /** + * A URL to the license used for the API. MUST be in the format of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - url} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#license-object | OpenAPI 3.0.4 License Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#license-object | OpenAPI 3.0.3 License Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#license-object | OpenAPI 3.0.2 License Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#license-object | OpenAPI 3.0.1 License Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#license-object | OpenAPI 3.0.0 License Object - url} | + * @property `url` - Optional A URL to the license used for the API + * + * @example "https://opensource.org/license/mit/" + * @example "http://www.apache.org/licenses/LICENSE-2.0.html" + * @example "https://example.com/licenses/proprietary-1.0" + */ + url?: LicenseURL; +} diff --git a/3.0/paths.ts b/3.0/paths.ts new file mode 100644 index 0000000..81c82bc --- /dev/null +++ b/3.0/paths.ts @@ -0,0 +1,2039 @@ +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +import type { Reference } from "./references"; +import type { Schema } from "./schema"; +import type { SecurityRequirement } from "./security"; +import type { Server } from "./servers"; +import type { ResponsesMap } from "./status"; + +/** + * ----- + * Paths Object + * ----- + * + * Holds the relative paths to the individual endpoints and their operations. + * + * The Paths Object holds the relative paths to the individual endpoints and their operations. + * The path is appended to the URL from the Server Object in order to construct the full URL. + * The Paths MAY be empty, due to ACL constraints. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#paths-object | OpenAPI 3.0.4 Paths} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#paths-object | OpenAPI 3.0.3 Paths} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#paths-object | OpenAPI 3.0.2 Paths} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#paths-object | OpenAPI 3.0.1 Paths} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#paths-object | OpenAPI 3.0.0 Paths} | + * + * ----- + * Fields + * ----- + * + * @property `/{path}` - A relative path to an individual endpoint + * @property `x-${string}` - Specification Extensions + * + * @note + * The field name MUST begin with a slash. The path is appended (no relative URL resolution) + * to the expanded URL from the Server Object's url field in order to construct the full URL. + * Path templating is allowed. When matching URLs, concrete (non-templated) paths would be + * matched before their templated counterparts. + * + * ----- + * Examples + * ----- + * + * @example (simple paths): + * ```ts + * const paths: Paths = { + * "/pets": { + * get: { + * summary: "List all pets", + * responses: { + * "200": { + * description: "A list of pets" + * } + * } + * } + * }, + * "/pets/{petId}": { + * get: { + * summary: "Get a pet by ID", + * parameters: [ + * { name: "petId", in: "path", required: true, schema: { type: "string" } } + * ], + * responses: { + * "200": { + * description: "A pet" + * } + * } + * } + * } + * }; + * ``` + */ +export type Paths = Record & Extension; + +/** + * ----- + * Path Item Object + * ----- + * + * Describes the operations available on a single path. + * A Path Item MAY be empty, due to ACL constraints. + * + * The Path Item Object describes the operations available on a single path. It can + * contain a summary and description that apply to all operations on the path, as well + * as individual operation definitions for each HTTP method. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item} | + * + * ----- + * Fields + * ----- + * + * @property `$ref` - Optional Allows for an external definition of this path item + * @property `summary` - Optional An optional, string summary, intended to apply to all operations in this path + * @property `description` - Optional An optional, string description, intended to apply to all operations in this path + * @property `get` - Optional A definition of a GET operation on this path + * @property `put` - Optional A definition of a PUT operation on this path + * @property `post` - Optional A definition of a POST operation on this path + * @property `delete` - Optional A definition of a DELETE operation on this path + * @property `options` - Optional A definition of an OPTIONS operation on this path + * @property `head` - Optional A definition of a HEAD operation on this path + * @property `patch` - Optional A definition of a PATCH operation on this path + * @property `trace` - Optional A definition of a TRACE operation on this path + * @property `servers` - Optional An alternative server array to service all operations in this path + * @property `parameters` - Optional A list of parameters that are applicable for all the operations described under this path + * @property `x-${string}` - Specification Extensions + * + * @note + * All operation fields are optional. Parameters can be overridden at the operation level. + * In OpenAPI 3.0.1+, the `servers` property was clarified to allow alternative server + * arrays that override the global servers for operations on this specific path. + * + * ----- + * Examples + * ----- + * + * @example (simple path item): + * ```ts + * const pathItem: PathItemObject = { + * get: { + * summary: "List users", + * responses: { + * "200": { + * description: "A list of users", + * content: { + * "application/json": { + * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } + * } + * } + * } + * } + * } + * }; + * ``` + * + * @example (path item with shared parameters): + * ```ts + * const pathItem: PathItemObject = { + * summary: "User management operations", + * parameters: [ + * { name: "userId", in: "path", required: true, schema: { type: "string" } } + * ], + * get: { summary: "Get user" }, + * put: { summary: "Update user" }, + * delete: { summary: "Delete user" } + * }; + * ``` + */ +export type PathItemObject = + | ({ + /** + * Allows for an external definition of this path item. The referenced structure + * MUST be in the format of a Path Item Object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - $ref} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - $ref} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - $ref} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - $ref} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - $ref} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - $ref} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - $ref} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - $ref} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - $ref} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - $ref} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - $ref} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - $ref} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - $ref} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - $ref} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - $ref} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - $ref} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - $ref} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - $ref} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - $ref} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - $ref} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - $ref} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - $ref} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - $ref} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - $ref} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - $ref} | + * @property `$ref` - Optional Allows for an external definition of this path item + */ + $ref?: string; + + /** + * An optional, string summary, intended to apply to all operations in this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - summary} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - summary} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - summary} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - summary} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - summary} | + * @property `summary` - Optional An optional, string summary, intended to apply to all operations in this path + * + * @example "User management operations" + */ + summary?: string; + + /** + * An optional, string description, intended to apply to all operations in this path. + * CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - description} | + * @property `description` - Optional An optional, string description, intended to apply to all operations in this path + * + * @example "Operations for managing users in the system" + */ + description?: string; + + /** + * A definition of a GET operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - get} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - get} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - get} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - get} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - get} | + * @property `get` - Optional A definition of a GET operation on this path + * + * @example { summary: "Get users", responses: { "200": { description: "Success" } } } + */ + get?: Operation; + + /** + * A definition of a PUT operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - put} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - put} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - put} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - put} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - put} | + * @property `put` - Optional A definition of a PUT operation on this path + * + * @example { summary: "Update user", responses: { "200": { description: "Success" } } } + */ + put?: Operation; + + /** + * A definition of a POST operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - post} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - post} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - post} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - post} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - post} | + * @property `post` - Optional A definition of a POST operation on this path + * + * @example { summary: "Create user", responses: { "201": { description: "Created" } } } + */ + post?: Operation; + + /** + * A definition of a DELETE operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - delete} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - delete} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - delete} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - delete} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - delete} | + * @property `delete` - Optional A definition of a DELETE operation on this path + * + * @example { summary: "Delete user", responses: { "204": { description: "No Content" } } } + */ + delete?: Operation; + + /** + * A definition of an OPTIONS operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - options} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - options} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - options} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - options} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - options} | + * @property `options` - Optional A definition of an OPTIONS operation on this path + * + * @example { summary: "Get options", responses: { "200": { description: "Options" } } } + */ + options?: Operation; + + /** + * A definition of a HEAD operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - head} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - head} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - head} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - head} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - head} | + * @property `head` - Optional A definition of a HEAD operation on this path + * + * @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } } + */ + head?: Operation; + + /** + * A definition of a PATCH operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - patch} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - patch} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - patch} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - patch} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - patch} | + * @property `patch` - Optional A definition of a PATCH operation on this path + * + * @example { summary: "Partially update user", responses: { "200": { description: "Success" } } } + */ + patch?: Operation; + + /** + * A definition of a TRACE operation on this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - trace} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - trace} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - trace} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - trace} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - trace} | + * @property `trace` - Optional A definition of a TRACE operation on this path + * + * @example { summary: "Trace request", responses: { "200": { description: "Success" } } } + */ + trace?: Operation; + + /** + * An alternative server array to service all operations in this path. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - servers} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - servers} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - servers} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - servers} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - servers} | + * @property `servers` - Optional An alternative server array to service all operations in this path + * + * @example [{ url: "https://api.example.com/v1" }] + */ + servers?: Server[]; + + /** + * A list of parameters that are applicable for all the operations described + * under this path. These parameters can be overridden at the operation level, + * but cannot be removed there. The list MUST NOT include duplicated parameters. + * A unique parameter is defined by a combination of a name and location. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item Object - parameters} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item Object - parameters} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item Object - parameters} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item Object - parameters} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item Object - parameters} | + * @property `parameters` - Optional A list of parameters that are applicable for all the operations described under this path + * + * @example [{ name: "limit", in: "query", schema: { type: "integer" } }] + */ + parameters?: Array; + } & Extension) + | Reference; + +/** + * ----- + * Operation Object + * ----- + * + * Describes a single API operation on a path. + * + * The Operation Object describes a single API operation on a path. It contains + * information about the operation including its parameters, request body, responses, + * and security requirements. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation} | + * + * ----- + * Fields + * ----- + * + * @property `tags` - Optional A list of tags for API documentation control + * @property `summary` - Optional A short summary of what the operation does + * @property `description` - Optional A verbose explanation of the operation behavior + * @property `externalDocs` - Optional Additional external documentation for this operation + * @property `operationId` - Optional Unique string used to identify the operation + * @property `parameters` - Optional A list of parameters that are applicable for this operation + * @property `requestBody` - Optional The request body applicable for this operation + * @property `responses` - Required The list of possible responses as they are returned from executing this operation + * @property `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation + * @property `deprecated` - Optional Declares this operation to be deprecated + * @property `security` - Optional A declaration of which security mechanisms can be used for this operation + * @property `servers` - Optional An alternative server array to service this operation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `responses` field is required and MUST contain at least one response. + * In OpenAPI 3.0.1+, the `operationId` field was clarified to be case-sensitive + * and must be unique across all operations in the API. The `servers` property + * was clarified to allow alternative server arrays that override the global + * servers for this specific operation. + * + * ----- + * Examples + * ----- + * + * @example (simple operation): + * ```ts + * const operation: Operation = { + * summary: "Get users", + * responses: { + * "200": { + * description: "A list of users", + * content: { + * "application/json": { + * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } + * } + * } + * } + * } + * }; + * ``` + * + * @example (operation with request body): + * ```ts + * const operation: Operation = { + * summary: "Create user", + * operationId: "createUser", + * requestBody: { + * description: "User data", + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/User" } + * } + * } + * }, + * responses: { + * "201": { + * description: "User created", + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/User" } + * } + * } + * } + * } + * }; + * ``` + */ +export interface Operation extends Extension { + /** + * A list of tags for API documentation control. Tags can be used for logical + * grouping of operations by resources or any other qualifier. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - tags} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - tags} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - tags} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - tags} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - tags} | + * @property `tags` - Optional A list of tags for API documentation control + * + * @example ["users", "authentication"] + * @example ["pets"] + */ + tags?: string[]; + + /** + * A short summary of what the operation does. For maximum readability in + * OpenAPI-UI, this field SHOULD be less than 120 characters. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - summary} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - summary} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - summary} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - summary} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - summary} | + * @property `summary` - Optional A short summary of what the operation does + * + * @example "Get user by ID" + * @example "Create a new pet" + */ + summary?: string; + + /** + * A verbose explanation of the operation behavior. CommonMark syntax MAY be used + * for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - description} | + * @property `description` - Optional A verbose explanation of the operation behavior + * + * @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information." + */ + description?: string; + + /** + * Additional external documentation for this operation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - externalDocs} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - externalDocs} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - externalDocs} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - externalDocs} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - externalDocs} | + * @property `externalDocs` - Optional Additional external documentation for this operation + * + * @example { description: "Find out more about this operation", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Unique string used to identify the operation. The id MUST be unique among + * all operations described in the API. Tools and libraries MAY use the + * operationId to uniquely identify an operation, therefore, it is recommended + * to follow common programming naming conventions. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - operationId} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - operationId} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - operationId} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - operationId} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - operationId} | + * @property `operationId` - Optional Unique string used to identify the operation + * + * @example "getUserById" + * @example "createPet" + */ + operationId?: string; + + /** + * A list of parameters that are applicable for this operation. If a parameter + * is already defined at the Path Item, the new definition will override it + * but can never remove it. The list MUST NOT include duplicated parameters. + * A unique parameter is defined by a combination of a name and location. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - parameters} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - parameters} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - parameters} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - parameters} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - parameters} | + * @property `parameters` - Optional A list of parameters that are applicable for this operation + * + * @example [{ name: "id", in: "path", required: true, schema: { type: "string" } }] + */ + parameters?: Array; + + /** + * The request body applicable for this operation. The requestBody is only + * supported in HTTP methods where the HTTP 1.1 specification has explicitly + * defined semantics for request bodies. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - requestBody} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - requestBody} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - requestBody} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - requestBody} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - requestBody} | + * @property `requestBody` - Optional The request body applicable for this operation + * + * @example { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } + */ + requestBody?: RequestBody | Reference; + + /** + * The list of possible responses as they are returned from executing this operation. + * This field MUST be present and MUST contain at least one response. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - responses} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - responses} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - responses} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - responses} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - responses} | + * @property `responses` - Required The list of possible responses as they are returned from executing this operation + * + * @example { "200": { description: "Success", content: { "application/json": { schema: { type: "object" } } } } } + */ + responses: ResponsesMap; + + /** + * A map of possible out-of band callbacks related to the parent operation. + * The key is a unique identifier for the Callback Object. Each value in the map + * is a Callback Object that describes a request that may be initiated by the API + * provider and the expected responses. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - callbacks} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - callbacks} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - callbacks} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - callbacks} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - callbacks} | + * @property `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation + * + * @example { "myCallback": { "{$request.body#/callbackUrl}": { post: { ... } } } } + */ + callbacks?: Record; + + /** + * Declares this operation to be deprecated. Consumers SHOULD refrain from usage + * of the declared operation. Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - deprecated} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - deprecated} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - deprecated} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - deprecated} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - deprecated} | + * @property `deprecated` - Optional Declares this operation to be deprecated + * + * @default false + * @example true + */ + deprecated?: boolean; + + /** + * A declaration of which security mechanisms can be used for this operation. + * The list of values includes alternative security requirement objects that can be used. + * Only one of the security requirement objects need to be satisfied to authorize a request. + * This definition overrides any declared top-level security. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - security} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - security} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - security} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - security} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - security} | + * @property `security` - Optional A declaration of which security mechanisms can be used for this operation + * + * @example [{ "api_key": [] }] + * @example [{ "oauth2": ["read", "write"] }] + */ + security?: SecurityRequirement[]; + + /** + * An alternative server array to service this operation. If an alternative + * server object is specified at the Path Item Object or Root level, it will + * be overridden by this value. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation Object - servers} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation Object - servers} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation Object - servers} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation Object - servers} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation Object - servers} | + * @property `servers` - Optional An alternative server array to service this operation + * + * @example [{ url: "https://api.example.com/v1" }] + */ + servers?: Server[]; +} + +/** + * ----- + * Parameter Object + * ----- + * + * Describes a single operation parameter. + * A unique parameter is defined by a combination of a name and location. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The name of the parameter + * @property `in` - Required The location of the parameter + * @property `description` - Optional A brief description of the parameter + * @property `required` - Optional Determines whether this parameter is mandatory + * @property `deprecated` - Optional Specifies that a parameter is deprecated + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters + * @property `style` - Optional Describes how the parameter value will be serialized + * @property `explode` - Optional When this is true, parameter values generate separate parameters + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * @property `schema` - Optional The schema defining the type used for the parameter + * @property `example` - Optional Example of the media type + * @property `examples` - Optional Examples of the media type + * @property `content` - Optional A map containing the representations for the parameter + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` and `in` fields are required. A parameter MUST contain either a `schema` property, or a `content` property, but not both. + * + * ----- + * Examples + * ----- + * + * @example (path parameter): + * ```ts + * const parameter: Parameter = { + * name: "id", + * in: "path", + * required: true, + * description: "User ID", + * schema: { type: "string" } + * }; + * ``` + * + * @example (query parameter): + * ```ts + * const parameter: Parameter = { + * name: "limit", + * in: "query", + * description: "Number of items to return", + * schema: { type: "integer", minimum: 1, maximum: 100 } + * }; + * ``` + */ +export interface Parameter extends Extension { + /** + * The name of the parameter. Parameter names are case sensitive. + * - If in is "path", the name field MUST correspond to the associated path segment + * - If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored + * - For all other cases, the name corresponds to the parameter name used by the in property + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - name} | + * @property `name` - Required The name of the parameter + * + * @example "id" + * @example "limit" + * @example "user" + */ + name: string; + + /** + * The location of the parameter. Possible values are "query", "header", "path" or "cookie". + * + * - **query**: Parameters that are appended to the URL + * - **header**: Custom headers that are expected as part of the request + * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL + * - **cookie**: Used to pass a specific cookie value to the API + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - in} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - in} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - in} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - in} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - in} | + * @property `in` - Required The location of the parameter + * + * @example "query" + * @example "path" + * @example "header" + * @example "cookie" + */ + in: "query" | "header" | "path" | "cookie"; + + /** + * A brief description of the parameter. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - description} | + * @property `description` - Optional A brief description of the parameter + * + * @example "User ID to retrieve" + * @example "Number of items to return" + */ + description?: string; + + /** + * Determines whether this parameter is mandatory. If the parameter location is "path", + * this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be + * included and its default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - required} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - required} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - required} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - required} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - required} | + * @property `required` - Optional Determines whether this parameter is mandatory + * + * @example true + * @example false + */ + required?: boolean; + + /** + * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - deprecated} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - deprecated} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - deprecated} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - deprecated} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - deprecated} | + * @property `deprecated` - Optional Specifies that a parameter is deprecated and SHOULD be transitioned out of usage + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * Sets the ability to pass empty-valued parameters. This is valid only for query + * parameters and allows sending a parameter with an empty value. Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - allowEmptyValue} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - allowEmptyValue} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - allowEmptyValue} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - allowEmptyValue} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - allowEmptyValue} | + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters + * + * @example true + * @example false + */ + allowEmptyValue?: boolean; + + /** + * Describes how the parameter value will be serialized depending on the type of the parameter value. + * Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - style} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - style} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - style} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - style} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - style} | + * @property `style` - Optional Describes how the parameter value will be serialized + * + * @example "form" + * @example "simple" + * @example "matrix" + * @example "label" + * @example "spaceDelimited" + * @example "pipeDelimited" + * @example "deepObject" + */ + style?: + | "matrix" + | "label" + | "form" + | "simple" + | "spaceDelimited" + | "pipeDelimited" + | "deepObject"; + + /** + * When this is true, parameter values of type array or object generate separate parameters + * for each value of the array or key-value pair of the map. For other types of parameters + * this property has no effect. When style is form, the default value is true. + * For all other styles, the default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - explode} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - explode} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - explode} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - explode} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - explode} | + * @property `explode` - Optional When this is true, parameter values of type array or object generate separate parameters + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the parameter value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only + * applies to parameters with an in value of query. The default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - allowReserved} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - allowReserved} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - allowReserved} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - allowReserved} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - allowReserved} | + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * + * @example true + * @example false + */ + allowReserved?: boolean; + + /** + * The schema defining the type used for the parameter. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - schema} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - schema} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - schema} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - schema} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - schema} | + * @property `schema` - Optional The schema defining the type used for the parameter + * + * @example { type: "string" } + * @example { type: "integer", minimum: 1, maximum: 100 } + */ + schema?: Schema; + + /** + * Example of the media type. The example SHOULD match the specified schema and encoding + * properties if present. The example object is mutually exclusive of the examples object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - example} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - example} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - example} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - example} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - example} | + * @property `example` - Optional Example of the media type + * + * @example "example-value" + * @example 42 + */ + example?: unknown; + + /** + * Examples of the media type. Each example SHOULD contain a value in the correct format + * as specified in the parameter encoding. The examples object is mutually exclusive of + * the example object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - examples} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - examples} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - examples} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - examples} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - examples} | + * @property `examples` - Optional Examples of the media type + * + * @example { "user1": { summary: "A user example", value: "user123" } } + */ + examples?: Record; + + /** + * A map containing the representations for the parameter. The key is the media type + * and the value describes it. The map MUST only contain one entry. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#parameter-object | OpenAPI 3.0.4 Parameter Object - content} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#parameter-object | OpenAPI 3.0.3 Parameter Object - content} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#parameter-object | OpenAPI 3.0.2 Parameter Object - content} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#parameter-object | OpenAPI 3.0.1 Parameter Object - content} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter Object - content} | + * @property `content` - Optional A map containing the representations for the parameter + * + * @example { "application/json": { schema: { type: "object" } } } + */ + content?: Record; +} + +/** + * ----- + * Request Body Object + * ----- + * + * Describes a single request body. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#request-body-object | OpenAPI 3.0.0 Request Body} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A brief description of the request body + * @property `content` - Required The content of the request body + * @property `required` - Optional Determines if the request body is required in the request + * @property `x-${string}` - Specification Extensions + * + * @note + * The `content` field is required. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification has explicitly defined semantics for request bodies. + * + * ----- + * Examples + * ----- + * + * @example (simple request body): + * ```ts + * const requestBody: RequestBody = { + * description: "User data", + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/User" } + * } + * } + * }; + * ``` + */ +export interface RequestBody extends Extension { + /** + * A brief description of the request body. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#request-body-object | OpenAPI 3.0.4 Request Body Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#request-body-object | OpenAPI 3.0.3 Request Body Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#request-body-object | OpenAPI 3.0.2 Request Body Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#request-body-object | OpenAPI 3.0.1 Request Body Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#request-body-object | OpenAPI 3.0.0 Request Body Object - description} | + * @property `description` - Optional A brief description of the request body + * + * @example "User data to create" + * @example "Pet information" + */ + description?: string; + + /** + * The content of the request body. The key is a media type or media type range + * and the value describes it. For requests that match multiple keys, only the + * most specific key is applicable. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#request-body-object | OpenAPI 3.0.4 Request Body Object - content} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#request-body-object | OpenAPI 3.0.3 Request Body Object - content} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#request-body-object | OpenAPI 3.0.2 Request Body Object - content} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#request-body-object | OpenAPI 3.0.1 Request Body Object - content} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#request-body-object | OpenAPI 3.0.0 Request Body Object - content} | + * @property `content` - Required The content of the request body + * + * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } + */ + content: Record; + + /** + * Determines if the request body is required in the request. Defaults to false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#request-body-object | OpenAPI 3.0.4 Request Body Object - required} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#request-body-object | OpenAPI 3.0.3 Request Body Object - required} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#request-body-object | OpenAPI 3.0.2 Request Body Object - required} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#request-body-object | OpenAPI 3.0.1 Request Body Object - required} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#request-body-object | OpenAPI 3.0.0 Request Body Object - required} | + * @property `required` - Optional Determines if the request body is required in the request + * + * @default false + * @example true + */ + required?: boolean; +} + +/** + * ----- + * Media Type Object + * ----- + * + * Each Media Type Object provides schema and examples for the media type identified by its key. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type} | + * + * ----- + * Fields + * ----- + * + * @property `schema` - Optional The schema defining the type used for the request body + * @property `example` - Optional Example of the media type + * @property `examples` - Optional Examples of the media type + * @property `encoding` - Optional A map between a property name and its encoding information + * @property `x-${string}` - Specification Extensions + * + * @note + * The `example` object is mutually exclusive of the `examples` object. + * + * ----- + * Examples + * ----- + * + * @example (simple media type): + * ```ts + * const mediaType: MediaType = { + * schema: { $ref: "#/components/schemas/User" } + * }; + * ``` + */ +export interface MediaType extends Extension { + /** + * The schema defining the type used for the request body. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#media-type-object | OpenAPI 3.0.4 Media Type Object - schema} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#media-type-object | OpenAPI 3.0.3 Media Type Object - schema} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#media-type-object | OpenAPI 3.0.2 Media Type Object - schema} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#media-type-object | OpenAPI 3.0.1 Media Type Object - schema} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type Object - schema} | + * @property `schema` - Optional The schema defining the type used for the request body + * + * @example { $ref: "#/components/schemas/User" } + * @example { type: "object", properties: { name: { type: "string" } } } + */ + schema?: Schema | Reference; + + /** + * Example of the media type. The example object SHOULD be in the correct format + * as specified by the media type. The example object is mutually exclusive of + * the examples object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#media-type-object | OpenAPI 3.0.4 Media Type Object - example} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#media-type-object | OpenAPI 3.0.3 Media Type Object - example} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#media-type-object | OpenAPI 3.0.2 Media Type Object - example} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#media-type-object | OpenAPI 3.0.1 Media Type Object - example} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type Object - example} | + * @property `example` - Optional Example of the media type + * + * @example { name: "John Doe", email: "john@example.com" } + */ + example?: unknown; + + /** + * Examples of the media type. Each example object SHOULD match the media type + * and specified schema if present. The examples object is mutually exclusive of + * the example object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#media-type-object | OpenAPI 3.0.4 Media Type Object - examples} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#media-type-object | OpenAPI 3.0.3 Media Type Object - examples} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#media-type-object | OpenAPI 3.0.2 Media Type Object - examples} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#media-type-object | OpenAPI 3.0.1 Media Type Object - examples} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type Object - examples} | + * @property `examples` - Optional Examples of the media type + * + * @example { "user1": { summary: "A user example", value: { name: "John" } } } + */ + examples?: Record; + + /** + * A map between a property name and its encoding information. The key, being the + * property name, MUST exist in the schema as a property. The encoding object SHALL + * only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#media-type-object | OpenAPI 3.0.4 Media Type Object - encoding} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#media-type-object | OpenAPI 3.0.3 Media Type Object - encoding} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#media-type-object | OpenAPI 3.0.2 Media Type Object - encoding} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#media-type-object | OpenAPI 3.0.1 Media Type Object - encoding} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type Object - encoding} | + * @property `encoding` - Optional A map between a property name and its encoding information + * + * @example { "profileImage": { contentType: "image/png" } } + */ + encoding?: Record; +} + +/** + * ----- + * Encoding Object + * ----- + * + * A single encoding definition applied to a single schema property. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding} | + * + * ----- + * Fields + * ----- + * + * @property `contentType` - Optional The Content-Type for encoding a specific property + * @property `headers` - Optional A map allowing additional information to be provided as headers + * @property `style` - Optional Describes how a specific property value will be serialized + * @property `explode` - Optional When this is true, property values generate separate parameters + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * @property `x-${string}` - Specification Extensions + * + * @note + * This attribute is only applicable to multipart and application/x-www-form-urlencoded request bodies. + * + * ----- + * Examples + * ----- + * + * @example (simple encoding): + * ```ts + * const encoding: Encoding = { + * contentType: "image/png" + * }; + * ``` + */ +export interface Encoding extends Extension { + /** + * The Content-Type for encoding a specific property. Default value depends on the property type. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#encoding-object | OpenAPI 3.0.4 Encoding Object - contentType} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#encoding-object | OpenAPI 3.0.3 Encoding Object - contentType} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#encoding-object | OpenAPI 3.0.2 Encoding Object - contentType} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#encoding-object | OpenAPI 3.0.1 Encoding Object - contentType} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding Object - contentType} | + * @property `contentType` - Optional The Content-Type for encoding a specific property + * + * @example "image/png" + * @example "application/json" + * @example "text/plain" + */ + contentType?: string; + + /** + * A map allowing additional information to be provided as headers, for example + * Content-Disposition. Content-Type is described separately and SHALL be ignored in this section. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#encoding-object | OpenAPI 3.0.4 Encoding Object - headers} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#encoding-object | OpenAPI 3.0.3 Encoding Object - headers} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#encoding-object | OpenAPI 3.0.2 Encoding Object - headers} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#encoding-object | OpenAPI 3.0.1 Encoding Object - headers} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding Object - headers} | + * @property `headers` - Optional A map allowing additional information to be provided as headers + * + * @example { "Content-Disposition": { schema: { type: "string" } } } + */ + headers?: Record; + + /** + * Describes how a specific property value will be serialized depending on its type. + * See Parameter Object for details on the style property. The behavior follows the + * same values as query parameters, including default values. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#encoding-object | OpenAPI 3.0.4 Encoding Object - style} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#encoding-object | OpenAPI 3.0.3 Encoding Object - style} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#encoding-object | OpenAPI 3.0.2 Encoding Object - style} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#encoding-object | OpenAPI 3.0.1 Encoding Object - style} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding Object - style} | + * @property `style` - Optional Describes how a specific property value will be serialized + * + * @example "form" + * @example "simple" + */ + style?: "form" | "spaceDelimited" | "pipeDelimited" | "deepObject"; + + /** + * When this is true, property values of type array or object generate separate parameters + * for each value of the array, or key-value-pair of the map. For other types of properties + * this property has no effect. When style is form, the default value is true. + * For all other styles, the default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#encoding-object | OpenAPI 3.0.4 Encoding Object - explode} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#encoding-object | OpenAPI 3.0.3 Encoding Object - explode} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#encoding-object | OpenAPI 3.0.2 Encoding Object - explode} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#encoding-object | OpenAPI 3.0.1 Encoding Object - explode} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding Object - explode} | + * @property `explode` - Optional When this is true, property values of type array or object generate separate parameters + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the parameter value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#encoding-object | OpenAPI 3.0.4 Encoding Object - allowReserved} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#encoding-object | OpenAPI 3.0.3 Encoding Object - allowReserved} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#encoding-object | OpenAPI 3.0.2 Encoding Object - allowReserved} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#encoding-object | OpenAPI 3.0.1 Encoding Object - allowReserved} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding Object - allowReserved} | + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * + * @example true + * @example false + */ + allowReserved?: boolean; +} + +/** + * ----- + * Response Object + * ----- + * + * Describes a single response from an API Operation, including design-time, static + * links to operations based on the response. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#response-object | OpenAPI 3.0.1 Response} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#response-object | OpenAPI 3.0.2 Response} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#response-object | OpenAPI 3.0.3 Response} | + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#response-object | OpenAPI 3.0.4 Response} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Required A short description of the response + * @property `headers` - Optional Maps a header name to its definition + * @property `content` - Optional A map containing descriptions of potential response payloads + * @property `links` - Optional A map of operations links that can be followed from the response + * @property `x-${string}` - Specification Extensions + * + * @note + * The `description` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple response): + * ```ts + * const response: Response = { + * description: "A list of users", + * content: { + * "application/json": { + * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } + * } + * } + * }; + * ``` + */ +export interface Response extends Extension { + /** + * A short description of the response. CommonMark syntax MAY be used for rich text representation. + * This field is required. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#response-object | OpenAPI 3.0.4 Response Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#response-object | OpenAPI 3.0.3 Response Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#response-object | OpenAPI 3.0.2 Response Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#response-object | OpenAPI 3.0.1 Response Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response Object - description} | + * @property `description` - Required A short description of the response + * + * @example "User successfully retrieved" + * @example "Bad request - invalid input parameters" + * @example "Internal server error" + */ + description: string; + + /** + * Maps a header name to its definition. RFC7230 states header names are case insensitive. + * If a response header is defined with the name "Content-Type", it SHALL be ignored. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#response-object | OpenAPI 3.0.4 Response Object - headers} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#response-object | OpenAPI 3.0.3 Response Object - headers} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#response-object | OpenAPI 3.0.2 Response Object - headers} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#response-object | OpenAPI 3.0.1 Response Object - headers} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response Object - headers} | + * @property `headers` - Optional Maps a header name to its definition + * + * @example { "X-RateLimit-Limit": { schema: { type: "integer" } } } + */ + headers?: Record; + + /** + * A map containing descriptions of potential response payloads. The key is a media type + * or media type range and the value describes it. For responses that match multiple keys, + * only the most specific key is applicable. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#response-object | OpenAPI 3.0.4 Response Object - content} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#response-object | OpenAPI 3.0.3 Response Object - content} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#response-object | OpenAPI 3.0.2 Response Object - content} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#response-object | OpenAPI 3.0.1 Response Object - content} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response Object - content} | + * @property `content` - Optional A map containing descriptions of potential response payloads + * + * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } + */ + content?: Record; + + /** + * A map of operations links that can be followed from the response. The key of the map + * is a short name for the link, following the naming constraints of the names for Component Objects. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#response-object | OpenAPI 3.0.4 Response Object - links} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#response-object | OpenAPI 3.0.3 Response Object - links} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#response-object | OpenAPI 3.0.2 Response Object - links} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#response-object | OpenAPI 3.0.1 Response Object - links} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response Object - links} | + * @property `links` - Optional A map of operations links that can be followed from the response + * + * @example { "GetUserByUserId": { operationId: "getUserById", parameters: { userId: "$response.body#/id" } } } + */ + links?: Record; +} + +/** + * ----- + * Header Object + * ----- + * + * The Header Object follows the structure of the Parameter Object with the following changes: + * 1. name MUST NOT be specified, it is given in the corresponding headers map. + * 2. in MUST NOT be specified, it is implicitly in header. + * 3. All traits that are affected by the location MUST be applicable to a location of header. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header} | + * + * ----- + * Examples + * ----- + * + * @example (simple header): + * ```ts + * const header: Header = { + * description: "The number of allowed requests in the current period", + * schema: { type: "integer" } + * }; + * ``` + */ +export interface Header extends Extension { + /** + * A brief description of the header. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - description} | + * @property `description` - Optional A brief description of the header + * + * @example "Rate limit for the current period" + * @example "Content type of the response" + */ + description?: string; + + /** + * Determines whether this header is mandatory. The property MAY be included and its default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - required} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - required} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - required} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - required} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - required} | + * @property `required` - Optional Determines whether this header is mandatory + * + * @example true + * @example false + */ + required?: boolean; + + /** + * Specifies that a header is deprecated and SHOULD be transitioned out of usage. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - deprecated} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - deprecated} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - deprecated} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - deprecated} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - deprecated} | + * @property `deprecated` - Optional Specifies that a header is deprecated and SHOULD be transitioned out of usage + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * Sets the ability to pass empty-valued headers. This is valid only for headers + * and allows sending a header with an empty value. Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - allowEmptyValue} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - allowEmptyValue} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - allowEmptyValue} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - allowEmptyValue} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - allowEmptyValue} | + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued headers + * + * @example true + * @example false + */ + allowEmptyValue?: boolean; + + /** + * Describes how the header value will be serialized. The default value is simple. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - style} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - style} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - style} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - style} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - style} | + * @property `style` - Optional Describes how the header value will be serialized + * + * @example "simple" + */ + style?: "simple"; + + /** + * When this is true, header values of type array or object generate separate headers + * for each value of the array or key-value pair of the map. For other types of headers + * this property has no effect. The default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - explode} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - explode} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - explode} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - explode} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - explode} | + * @property `explode` - Optional When this is true, header values of type array or object generate separate headers + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * The schema defining the type used for the header. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - schema} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - schema} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - schema} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - schema} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - schema} | + * @property `schema` - Optional The schema defining the type used for the header + * + * @example { type: "integer" } + * @example { type: "string" } + */ + schema?: Schema | Reference; + + /** + * Example of the media type. The example SHOULD match the specified schema and encoding + * properties if present. The example object is mutually exclusive of the examples object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - example} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - example} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - example} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - example} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - example} | + * @property `example` - Optional Example of the media type + * + * @example "example-value" + * @example 42 + */ + example?: unknown; + + /** + * Examples of the media type. Each example SHOULD contain a value in the correct format + * as specified in the header encoding. The examples object is mutually exclusive of + * the example object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - examples} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - examples} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - examples} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - examples} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - examples} | + * @property `examples` - Optional Examples of the media type + * + * @example { "header1": { summary: "A header example", value: "value123" } } + */ + examples?: Record; + + /** + * A map containing the representations for the header. The key is the media type + * and the value describes it. The map MUST only contain one entry. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#header-object | OpenAPI 3.0.4 Header Object - content} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#header-object | OpenAPI 3.0.3 Header Object - content} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#header-object | OpenAPI 3.0.2 Header Object - content} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#header-object | OpenAPI 3.0.1 Header Object - content} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header Object - content} | + * @property `content` - Optional A map containing the representations for the header + * + * @example { "application/json": { schema: { type: "object" } } } + */ + content?: Record; +} + +/** + * ----- + * Callback Object + * ----- + * + * A map of possible out-of band callbacks related to the parent operation. + * Each value in the map is a Path Item Object that describes a set of requests + * that may be initiated by the API provider and the expected responses. + * + * The key that identifies the Path Item Object is a runtime expression that can be + * evaluated in the context of a runtime HTTP request/response to identify the URL + * to be used for the callback request. A simple example might be `$request.body#/id`. + * A more complex example that uses a number of runtime expressions is + * `$request.body#/url~1callback`. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#callback-object | OpenAPI 3.0.4 Callback} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#callback-object | OpenAPI 3.0.3 Callback} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#callback-object | OpenAPI 3.0.2 Callback} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#callback-object | OpenAPI 3.0.1 Callback} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#callback-object | OpenAPI 3.0.0 Callback} | + * + * ----- + * Fields + * ----- + * + * @property `{expression}` - A runtime expression that evaluates to a URL for the callback + * @property `PathItemObject` - The Path Item Object that describes the callback request + * + * @note + * The key is a runtime expression that can be evaluated in the context of a runtime + * HTTP request/response to identify the URL to be used for the callback request. + * + * ----- + * Examples + * ----- + * + * @example (simple callback): + * ```ts + * const callback: Callback = { + * "{$request.body#/callbackUrl}": { + * post: { + * requestBody: { + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/SomePayload" } + * } + * } + * }, + * responses: { + * "200": { + * description: "webhook successfully processed" + * } + * } + * } + * } + * }; + * ``` + * + * @example (callback with multiple operations): + * ```ts + * const callback: Callback = { + * "{$request.body#/callbackUrl}": { + * post: { + * summary: "Callback for successful operation", + * requestBody: { + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/SuccessPayload" } + * } + * } + * }, + * responses: { + * "200": { description: "Callback processed successfully" } + * } + * }, + * get: { + * summary: "Callback for status check", + * responses: { + * "200": { description: "Status retrieved" } + * } + * } + * } + * }; + * ``` + * + * @example (callback with complex expression): + * ```ts + * const callback: Callback = { + * "{$request.body#/url~1callback}": { + * post: { + * requestBody: { + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/CallbackPayload" } + * } + * } + * }, + * responses: { + * "200": { description: "Callback received" } + * } + * } + * } + * }; + * ``` + */ +export type Callback = Record; + +/** + * ----- + * Link Object + * ----- + * + * The Link object represents a possible design-time link for a response. + * The presence of a link does not guarantee the caller's ability to successfully invoke it, + * rather it provides a known relationship and traversal mechanism between responses and other operations. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link} | + * + * ----- + * Fields + * ----- + * + * @property `operationRef` - Optional A relative or absolute reference to an OAS operation + * @property `operationId` - Optional The name of an existing, resolvable OAS operation + * @property `parameters` - Optional A map representing parameters to pass to an operation + * @property `requestBody` - Optional A literal value or expression to use as a request body + * @property `description` - Optional A description of the link + * @property `server` - Optional A server object to be used by the target operation + * @property `x-${string}` - Specification Extensions + * + * @note + * A linked operation MUST be identified using either an operationRef or operationId. + * + * ----- + * Examples + * ----- + * + * @example (link with operationId): + * ```ts + * const link: Link = { + * operationId: "getUserById", + * parameters: { + * userId: "$response.body#/id" + * } + * }; + * ``` + */ +export interface Link extends Extension { + /** + * A relative or absolute reference to an OAS operation. This field is mutually + * exclusive of the operationId field, and MUST point to an Operation Object. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#link-object | OpenAPI 3.0.4 Link Object - operationRef} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#link-object | OpenAPI 3.0.3 Link Object - operationRef} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#link-object | OpenAPI 3.0.2 Link Object - operationRef} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#link-object | OpenAPI 3.0.1 Link Object - operationRef} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link Object - operationRef} | + * @property `operationRef` - Optional A relative or absolute reference to an OAS operation + * + * @example "#/paths/~12.0~1repositories~1{username}/get" + * @example "https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get" + */ + operationRef?: string; + + /** + * The name of an existing, resolvable OAS operation, as defined with a unique operationId. + * This field is mutually exclusive of the operationRef field. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#link-object | OpenAPI 3.0.4 Link Object - operationId} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#link-object | OpenAPI 3.0.3 Link Object - operationId} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#link-object | OpenAPI 3.0.2 Link Object - operationId} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#link-object | OpenAPI 3.0.1 Link Object - operationId} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link Object - operationId} | + * @property `operationId` - Optional The name of an existing, resolvable OAS operation + * + * @example "getUserById" + * @example "createPet" + */ + operationId?: string; + + /** + * A map representing parameters to pass to an operation as specified with operationId + * or identified via operationRef. The key is the parameter name to be used, whereas + * the value can be a constant or an expression to be evaluated and passed to the linked operation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#link-object | OpenAPI 3.0.4 Link Object - parameters} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#link-object | OpenAPI 3.0.3 Link Object - parameters} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#link-object | OpenAPI 3.0.2 Link Object - parameters} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#link-object | OpenAPI 3.0.1 Link Object - parameters} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link Object - parameters} | + * @property `parameters` - Optional A map representing parameters to pass to an operation + * + * @example { userId: "$response.body#/id" } + * @example { limit: 10 } + */ + parameters?: Record; + + /** + * A literal value or expression to use as a request body when calling the target operation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#link-object | OpenAPI 3.0.4 Link Object - requestBody} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#link-object | OpenAPI 3.0.3 Link Object - requestBody} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#link-object | OpenAPI 3.0.2 Link Object - requestBody} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#link-object | OpenAPI 3.0.1 Link Object - requestBody} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link Object - requestBody} | + * @property `requestBody` - Optional A literal value or expression to use as a request body + * + * @example { name: "John Doe" } + * @example "$request.body#/user" + */ + requestBody?: unknown; + + /** + * A description of the link. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#link-object | OpenAPI 3.0.4 Link Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#link-object | OpenAPI 3.0.3 Link Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#link-object | OpenAPI 3.0.2 Link Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#link-object | OpenAPI 3.0.1 Link Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link Object - description} | + * @property `description` - Optional A description of the link + * + * @example "Get user by ID" + * @example "Create a new pet" + */ + description?: string; + + /** + * A server object to be used by the target operation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#link-object | OpenAPI 3.0.4 Link Object - server} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#link-object | OpenAPI 3.0.3 Link Object - server} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#link-object | OpenAPI 3.0.2 Link Object - server} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#link-object | OpenAPI 3.0.1 Link Object - server} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link Object - server} | + * @property `server` - Optional A server object to be used by the target operation + * + * @example { url: "https://api.example.com/v1" } + */ + server?: Server; +} + +/** + * ----- + * Example Object + * ----- + * + * In all cases, the example value is expected to be compatible with the type schema + * of its associated value. Tooling implementations MAY choose to validate compatibility + * automatically, and reject the example value(s) if incompatible. + * + * | Version | Reference | + * |---|-----| + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example} | + * + * ----- + * Fields + * ----- + * + * @property `summary` - Optional Short description for the example + * @property `description` - Optional Long description for the example + * @property `value` - Optional Embedded literal example + * @property `externalValue` - Optional A URL that points to the literal example + * @property `x-${string}` - Specification Extensions + * + * @note + * The `value` field and `externalValue` field are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (simple example): + * ```ts + * const example: Example = { + * summary: "A user example", + * value: { name: "John Doe", email: "john@example.com" } + * }; + * ``` + */ +export interface Example extends Extension { + /** + * Short description for the example. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#example-object | OpenAPI 3.0.4 Example Object - summary} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#example-object | OpenAPI 3.0.3 Example Object - summary} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#example-object | OpenAPI 3.0.2 Example Object - summary} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#example-object | OpenAPI 3.0.1 Example Object - summary} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example Object - summary} | + * @property `summary` - Optional Short description for the example + * + * @example "A user example" + * @example "An error response" + */ + summary?: string; + + /** + * Long description for the example. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#example-object | OpenAPI 3.0.4 Example Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#example-object | OpenAPI 3.0.3 Example Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#example-object | OpenAPI 3.0.2 Example Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#example-object | OpenAPI 3.0.1 Example Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example Object - description} | + * @property `description` - Optional Long description for the example + * + * @example "A complete user object with all fields populated" + * @example "An error response when the user is not found" + */ + description?: string; + + /** + * Embedded literal example. The value field and externalValue field are mutually exclusive. + * To represent examples of media types that cannot naturally represented in JSON or YAML, + * use a string value to contain the example, escaping where necessary. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#example-object | OpenAPI 3.0.4 Example Object - value} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#example-object | OpenAPI 3.0.3 Example Object - value} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#example-object | OpenAPI 3.0.2 Example Object - value} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#example-object | OpenAPI 3.0.1 Example Object - value} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example Object - value} | + * @property `value` - Optional Embedded literal example + * + * @example { name: "John Doe", email: "john@example.com" } + * @example "example string value" + */ + value?: unknown; + + /** + * A URL that points to the literal example. This provides the capability to reference + * examples that cannot easily be included in JSON or YAML documents. The value field + * and externalValue field are mutually exclusive. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#example-object | OpenAPI 3.0.4 Example Object - externalValue} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#example-object | OpenAPI 3.0.3 Example Object - externalValue} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#example-object | OpenAPI 3.0.2 Example Object - externalValue} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#example-object | OpenAPI 3.0.1 Example Object - externalValue} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example Object - externalValue} | + * @property `externalValue` - Optional A URL that points to the literal example + * + * @example "https://example.com/examples/user-example.json" + * @example "https://example.com/examples/error-example.xml" + */ + externalValue?: string; +} diff --git a/3.0/references.ts b/3.0/references.ts new file mode 100644 index 0000000..f00785a --- /dev/null +++ b/3.0/references.ts @@ -0,0 +1,58 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Reference Object + * ----- + * + * A simple object to allow referencing other components in the specification, + * internally and externally. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#reference-object | OpenAPI 3.0.4 Reference} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#reference-object | OpenAPI 3.0.3 Reference} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#reference-object | OpenAPI 3.0.2 Reference} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#reference-object | OpenAPI 3.0.1 Reference} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#reference-object | OpenAPI 3.0.0 Reference} | + * + * ----- + * Fields + * ----- + * + * @property `$ref` - Required The reference string + * @property `x-${string}` - Specification Extensions + * + * @note + * The `$ref` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple reference): + * ```ts + * const reference: Reference = { + * $ref: "#/components/schemas/User" + * }; + * ``` + */ +export interface Reference extends Extension { + /** + * The reference string. MUST be a valid JSON Reference. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#reference-object | OpenAPI 3.0.4 Reference Object - $ref} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#reference-object | OpenAPI 3.0.3 Reference Object - $ref} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#reference-object | OpenAPI 3.0.2 Reference Object - $ref} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#reference-object | OpenAPI 3.0.1 Reference Object - $ref} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#reference-object | OpenAPI 3.0.0 Reference Object - $ref} | + * @property `$ref` - Required The reference string + * + * @example "#/components/schemas/User" + * @example "#/components/responses/NotFound" + * @example "#/components/parameters/LimitParam" + */ + $ref: string; +} diff --git a/3.0.x/schema.ts b/3.0/schema.ts similarity index 60% rename from 3.0.x/schema.ts rename to 3.0/schema.ts index 5851498..da4ca15 100644 --- a/3.0.x/schema.ts +++ b/3.0/schema.ts @@ -1,17 +1,13 @@ import type { - ReferenceSchema, - StringSchema, - NumberSchema, - IntegerSchema, - BooleanSchema, - ArraySchema, - ObjectSchema, - CompositionSchema, -} from "./data-types" -import type { Reference } from "./references" -import type { XML } from "./xml" -import type { ExternalDocumentation } from "./externalDocs" -import type { Components } from "./components" + ArraySchema, + BooleanSchema, + CompositionSchema, + IntegerSchema, + NumberSchema, + ObjectSchema, + ReferenceSchema, + StringSchema, +} from "./data-types"; // Discriminator will be defined below to avoid circular reference /** @@ -40,14 +36,14 @@ import type { Components } from "./components" * Schema Types * ----- * - * @key `ReferenceSchema` - Reference-only schemas ($ref with optional description) - * @key `StringSchema` - String schemas with string-specific constraints - * @key `NumberSchema` - Number schemas with numeric constraints - * @key `IntegerSchema` - Integer schemas with integer constraints - * @key `BooleanSchema` - Boolean schemas with basic validation - * @key `ArraySchema` - Array schemas with array-specific constraints - * @key `ObjectSchema` - Object schemas with object-specific constraints - * @key `CompositionSchema` - Composition schemas (allOf/anyOf/oneOf/not) + * @property `ReferenceSchema` - Reference-only schemas ($ref with optional description) + * @property `StringSchema` - String schemas with string-specific constraints + * @property `NumberSchema` - Number schemas with numeric constraints + * @property `IntegerSchema` - Integer schemas with integer constraints + * @property `BooleanSchema` - Boolean schemas with basic validation + * @property `ArraySchema` - Array schemas with array-specific constraints + * @property `ObjectSchema` - Object schemas with object-specific constraints + * @property `CompositionSchema` - Composition schemas (allOf/anyOf/oneOf/not) * * @note * The discriminated union enforces these OpenAPI 3.0.x rules: @@ -100,15 +96,15 @@ import type { Components } from "./components" * }; * ``` */ -export type Schema = - | ReferenceSchema - | StringSchema - | NumberSchema - | IntegerSchema - | BooleanSchema - | ArraySchema - | ObjectSchema - | CompositionSchema +export type Schema = + | ReferenceSchema + | StringSchema + | NumberSchema + | IntegerSchema + | BooleanSchema + | ArraySchema + | ObjectSchema + | CompositionSchema; /** * ----- @@ -132,9 +128,9 @@ export type Schema = * Fields * ----- * - * @key `propertyName` - The name of the property in the schema that is used as a discriminator - * @key `mapping` - An object to hold mappings between payload values and schema names or references - * @key `x-${string}` - Specification Extensions + * @property `propertyName` - The name of the property in the schema that is used as a discriminator + * @property `mapping` - An object to hold mappings between payload values and schema names or references + * @property `x-${string}` - Specification Extensions * * @note * The discriminator property name MUST be defined at this schema and it MUST be in the @@ -164,22 +160,40 @@ export type Schema = * ``` */ export interface Discriminator { - /** - * The name of the property in the schema that is used as a discriminator. - * - * @example "petType" - * @example "type" - * @example "kind" - */ - propertyName: string + /** + * The name of the property in the schema that is used as a discriminator. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#discriminator-object | OpenAPI 3.0.4 Discriminator Object - propertyName} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#discriminator-object | OpenAPI 3.0.3 Discriminator Object - propertyName} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#discriminator-object | OpenAPI 3.0.2 Discriminator Object - propertyName} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#discriminator-object | OpenAPI 3.0.1 Discriminator Object - propertyName} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#discriminator-object | OpenAPI 3.0.0 Discriminator Object - propertyName} | + * @property `propertyName` - Required The name of the property in the schema that is used as a discriminator + * + * @example "petType" + * @example "type" + * @example "kind" + */ + propertyName: string; - /** - * An object to hold mappings between payload values and schema names or references. - * - * @example { "dog": "Dog", "cat": "Cat" } - * @example { "admin": "AdminUser", "user": "RegularUser" } - */ - mapping?: Record + /** + * An object to hold mappings between payload values and schema names or references. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#discriminator-object | OpenAPI 3.0.4 Discriminator Object - mapping} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#discriminator-object | OpenAPI 3.0.3 Discriminator Object - mapping} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#discriminator-object | OpenAPI 3.0.2 Discriminator Object - mapping} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#discriminator-object | OpenAPI 3.0.1 Discriminator Object - mapping} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#discriminator-object | OpenAPI 3.0.0 Discriminator Object - mapping} | + * @property `mapping` - Optional An object to hold mappings between payload values and schema names or references + * + * @example { "dog": "Dog", "cat": "Cat" } + * @example { "admin": "AdminUser", "user": "RegularUser" } + */ + mapping?: Record; } /** @@ -188,7 +202,7 @@ export interface Discriminator { * ----- * * A metadata object that allows for more fine-tuned XML model definitions. - * When using arrays, XML element names are not inferred (for singular/plural forms) + * When using arrays, XML element names are not inferred (for singular/plural forms) * and the name property should be used to add that information. * * | Version | Reference | @@ -203,12 +217,12 @@ export interface Discriminator { * Fields * ----- * - * @key `name` - Replaces the name of the element/attribute used for the described schema property - * @key `namespace` - The URL of the namespace definition - * @key `prefix` - The prefix to be used for the name - * @key `attribute` - Declares whether the property definition translates to an attribute instead of an element - * @key `wrapped` - Signifies whether the array is wrapped - * @key `x-${string}` - Specification Extensions + * @property `name` - Replaces the name of the element/attribute used for the described schema property + * @property `namespace` - The URL of the namespace definition + * @property `prefix` - The prefix to be used for the name + * @property `attribute` - Declares whether the property definition translates to an attribute instead of an element + * @property `wrapped` - Signifies whether the array is wrapped + * @property `x-${string}` - Specification Extensions * * @note * When defined within items, it will affect the name of the individual XML elements within the list. diff --git a/3.0/security.ts b/3.0/security.ts new file mode 100644 index 0000000..708671c --- /dev/null +++ b/3.0/security.ts @@ -0,0 +1,571 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Security Scheme Object + * ----- + * + * Defines a security scheme that can be used by the operations. + * Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), + * OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, + * and OpenID Connect Discovery. + * + * The Security Scheme Object defines a security scheme that can be used by the operations. + * It supports various authentication methods including HTTP authentication, API keys, + * OAuth2 flows, and OpenID Connect Discovery. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Required The type of the security scheme + * @property `description` - Optional A short description for security scheme + * @property `name` - Optional The name of the header, query or cookie parameter to be used + * @property `in` - Optional The location of the API key + * @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header + * @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted + * @property `flows` - Optional An object containing configuration information for the flow types supported + * @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values + * @property `x-${string}` - Specification Extensions + * + * @note + * The `type` field is required. The `name` and `in` fields are required for apiKey type. + * In OpenAPI 3.0.1+, the `bearerFormat` field was clarified to be a hint to the client + * about how the bearer token is formatted, and the `openIdConnectUrl` field was clarified + * to be a URL that can be used to discover OAuth2 configuration values. + * + * ----- + * Examples + * ----- + * + * @example (API key): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "apiKey", + * in: "header", + * name: "X-API-Key" + * }; + * ``` + * + * @example (OAuth2): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "oauth2", + * flows: { + * authorizationCode: { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access", + * "write": "Write access" + * } + * } + * } + * }; + * ``` + * + * @example (HTTP Bearer): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "http", + * scheme: "bearer", + * bearerFormat: "JWT" + * }; + * ``` + * + * @example (OpenID Connect): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "openIdConnect", + * openIdConnectUrl: "https://example.com/.well-known/openid_configuration" + * }; + * ``` + */ +export interface SecurityScheme extends Extension { + /** + * The type of the security scheme. This field is required. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - type} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - type} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - type} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - type} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - type} | + * @property `type` - Required The type of the security scheme + * + * @example "apiKey" + * @example "http" + * @example "oauth2" + * @example "openIdConnect" + */ + type: "apiKey" | "http" | "oauth2" | "openIdConnect"; + + /** + * A short description for security scheme. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - description} | + * @property `description` - Optional A short description for security scheme + * + * @example "API key authentication" + * @example "OAuth 2.0 authentication" + */ + description?: string; + + /** + * The name of the header, query or cookie parameter to be used. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - name} | + * @property `name` - Optional The name of the header, query or cookie parameter to be used + * + * @example "X-API-Key" + * @example "Authorization" + */ + name?: string; + + /** + * The location of the API key. Valid values are "query", "header" or "cookie". + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - in} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - in} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - in} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - in} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - in} | + * @property `in` - Optional The location of the API key + * + * @example "query" + * @example "header" + * @example "cookie" + */ + in?: "query" | "header" | "cookie"; + + /** + * The name of the HTTP Authorization scheme to be used in the Authorization header. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - scheme} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - scheme} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - scheme} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - scheme} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - scheme} | + * @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header + * + * @example "bearer" + * @example "basic" + */ + scheme?: string; + + /** + * A hint to the client to identify how the bearer token is formatted. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - bearerFormat} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - bearerFormat} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - bearerFormat} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - bearerFormat} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - bearerFormat} | + * @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted + * + * @example "JWT" + * @example "Bearer" + */ + bearerFormat?: string; + + /** + * An object containing configuration information for the flow types supported. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - flows} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - flows} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - flows} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - flows} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - flows} | + * @property `flows` - Optional An object containing configuration information for the flow types supported + * + * @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } } + */ + flows?: OAuthFlows; + + /** + * OpenId Connect URL to discover OAuth2 configuration values. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - openIdConnectUrl} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - openIdConnectUrl} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - openIdConnectUrl} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - openIdConnectUrl} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - openIdConnectUrl} | + * @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values + * + * @example "https://example.com/.well-known/openid_configuration" + */ + openIdConnectUrl?: string; +} + +/** + * ----- + * OAuth Flows Object + * ----- + * + * Allows configuration of the supported OAuth Flows. + * + * The OAuth Flows Object allows configuration of the supported OAuth Flows. Each property + * represents a specific OAuth flow type and contains configuration details for that flow. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows} | + * + * ----- + * Fields + * ----- + * + * @property `implicit` - Optional Configuration for the OAuth Implicit flow + * @property `password` - Optional Configuration for the OAuth Resource Owner Password flow + * @property `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow + * @property `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow + * @property `x-${string}` - Specification Extensions + * + * @note + * All OAuth flow configurations are optional. At least one flow type should be provided + * for a complete OAuth2 security scheme configuration. + * + * ----- + * Examples + * ----- + * + * @example (authorization code flow): + * ```ts + * const flows: OAuthFlows = { + * authorizationCode: { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access to resources", + * "write": "Write access to resources" + * } + * } + * }; + * ``` + * + * @example (multiple flows): + * ```ts + * const flows: OAuthFlows = { + * implicit: { + * authorizationUrl: "https://example.com/oauth/authorize", + * scopes: { + * "read": "Read access" + * } + * }, + * clientCredentials: { + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "admin": "Administrative access" + * } + * } + * }; + * ``` + */ +export interface OAuthFlows extends Extension { + /** + * Configuration for the OAuth Implicit flow. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - implicit} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - implicit} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - implicit} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - implicit} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - implicit} | + * @property `implicit` - Optional Configuration for the OAuth Implicit flow + * + * @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { read: "Read access" } } + */ + implicit?: OAuthFlow; + + /** + * Configuration for the OAuth Resource Owner Password flow. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - password} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - password} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - password} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - password} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - password} | + * @property `password` - Optional Configuration for the OAuth Resource Owner Password flow + * + * @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } } + */ + password?: OAuthFlow; + + /** + * Configuration for the OAuth Client Credentials flow. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - clientCredentials} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - clientCredentials} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - clientCredentials} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - clientCredentials} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - clientCredentials} | + * @property `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow + * + * @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } } + */ + clientCredentials?: OAuthFlow; + + /** + * Configuration for the OAuth Authorization Code flow. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - authorizationCode} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - authorizationCode} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - authorizationCode} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - authorizationCode} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - authorizationCode} | + * @property `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow + * + * @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } } + */ + authorizationCode?: OAuthFlow; +} + +/** + * ----- + * OAuth Flow Object + * ----- + * + * Configuration details for a supported OAuth Flow. + * + * The OAuth Flow Object contains configuration details for a specific OAuth flow. + * Different OAuth flows require different combinations of URLs and parameters. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow} | + * + * ----- + * Fields + * ----- + * + * @property `authorizationUrl` - Optional The authorization URL to be used for this flow + * @property `tokenUrl` - Optional The token URL to be used for this flow + * @property `refreshUrl` - Optional The URL to be used for obtaining refresh tokens + * @property `scopes` - Required The available scopes for the OAuth2 security scheme + * @property `x-${string}` - Specification Extensions + * + * @note + * The `scopes` field is required for all OAuth flows. The `authorizationUrl` is required for + * `implicit` and `authorizationCode` flows. The `tokenUrl` is required for `password`, + * `clientCredentials`, and `authorizationCode` flows. + * + * ----- + * Examples + * ----- + * + * @example (authorization code flow): + * ```ts + * const flow: OAuthFlow = { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access to resources", + * "write": "Write access to resources" + * } + * }; + * ``` + * + * @example (implicit flow): + * ```ts + * const flow: OAuthFlow = { + * authorizationUrl: "https://example.com/oauth/authorize", + * scopes: { + * "read": "Read access", + * "write": "Write access" + * } + * }; + * ``` + * + * @example (client credentials flow): + * ```ts + * const flow: OAuthFlow = { + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "admin": "Administrative access" + * } + * }; + * ``` + */ +export interface OAuthFlow extends Extension { + /** + * The authorization URL to be used for this flow. This MUST be in the form of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - authorizationUrl} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - authorizationUrl} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - authorizationUrl} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - authorizationUrl} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - authorizationUrl} | + * @property `authorizationUrl` - Optional The authorization URL to be used for this flow + * + * @example "https://example.com/oauth/authorize" + * @example "https://api.example.com/oauth/authorize" + */ + authorizationUrl?: string; + + /** + * The token URL to be used for this flow. This MUST be in the form of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - tokenUrl} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - tokenUrl} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - tokenUrl} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - tokenUrl} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - tokenUrl} | + * @property `tokenUrl` - Optional The token URL to be used for this flow + * + * @example "https://example.com/oauth/token" + * @example "https://api.example.com/oauth/token" + */ + tokenUrl?: string; + + /** + * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - refreshUrl} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - refreshUrl} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - refreshUrl} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - refreshUrl} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - refreshUrl} | + * @property `refreshUrl` - Optional The URL to be used for obtaining refresh tokens + * + * @example "https://example.com/oauth/refresh" + * @example "https://api.example.com/oauth/refresh" + */ + refreshUrl?: string; + + /** + * The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - scopes} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - scopes} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - scopes} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - scopes} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - scopes} | + * @property `scopes` - Required The available scopes for the OAuth2 security scheme + * + * @example { "read": "Read access", "write": "Write access" } + * @example { "admin": "Administrative access" } + */ + scopes: Record; +} + +/** + * ----- + * Security Requirement Object + * ----- + * + * Lists the required security schemes to execute this operation. + * + * The Security Requirement Object lists the required security schemes to execute + * this operation. The name used for each property MUST correspond to a security + * scheme declared in the Security Schemes under the Components Object. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-requirement-object | OpenAPI 3.0.4 Security Requirement} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-requirement-object | OpenAPI 3.0.3 Security Requirement} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-requirement-object | OpenAPI 3.0.2 Security Requirement} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-requirement-object | OpenAPI 3.0.1 Security Requirement} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-requirement-object | OpenAPI 3.0.0 Security Requirement} | + * + * ----- + * Fields + * ----- + * + * @property `{name}` - Each name MUST correspond to a security scheme declared in the Security Schemes + * + * @note + * Security Requirement Objects that contain multiple schemes require that all schemes + * MUST be satisfied for a request to be authorized. When a list of Security Requirement + * Objects is defined, only one of the Security Requirement Objects in the list needs to + * be satisfied to authorize the request. + * + * If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list + * of scope names required for the execution. For other security scheme types, the array + * MUST be empty. + * + * ----- + * Examples + * ----- + * + * @example (API key security): + * ```ts + * const requirement: SecurityRequirement = { + * "api_key": [] + * }; + * ``` + * + * @example (OAuth2 security with scopes): + * ```ts + * const requirement: SecurityRequirement = { + * "petstore_auth": [ + * "write:pets", + * "read:pets" + * ] + * }; + * ``` + * + * @example (multiple schemes required): + * ```ts + * const requirement: SecurityRequirement = { + * "api_key": [], + * "oauth2": ["read", "write"] + * }; + * ``` + */ +export interface SecurityRequirement { + [schemeName: string]: string[]; +} diff --git a/3.0/servers.ts b/3.0/servers.ts new file mode 100644 index 0000000..783bac6 --- /dev/null +++ b/3.0/servers.ts @@ -0,0 +1,251 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Server Object + * ----- + * + * An object representing a Server. + * + * The Server Object represents a server that hosts the API. It can contain a URL, + * description, and server variables for URL template substitution. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-object | OpenAPI 3.0.4 Server} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-object | OpenAPI 3.0.3 Server} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-object | OpenAPI 3.0.2 Server} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-object | OpenAPI 3.0.1 Server} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-object | OpenAPI 3.0.0 Server} | + * + * ----- + * Fields + * ----- + * + * @property `url` - Required A URL to the target host + * @property `description` - Optional An optional string describing the host designated by the URL + * @property `variables` - Optional A map between a variable name and its value + * @property `x-${string}` - Specification Extensions + * + * @note + * The `url` field is required. The `url` supports Server Variables and MAY be relative. + * In OpenAPI 3.0.1+, the `url` field was clarified to support Server Variables and + * MAY be relative to indicate that the host location is relative to the location + * where the OpenAPI document is being served. + * + * ----- + * Examples + * ----- + * + * @example (simple server): + * ```ts + * const server: Server = { + * url: "https://development.gigantic-server.com/v1", + * description: "Development server" + * }; + * ``` + * + * @example (server with variables): + * ```ts + * const server: Server = { + * url: "https://{username}.gigantic-server.com:{port}/{basePath}", + * description: "The production API server", + * variables: { + * username: { + * default: "demo", + * description: "this value is assigned by the service provider" + * }, + * port: { + * enum: ["8443", "443"], + * default: "8443" + * }, + * basePath: { + * default: "v2" + * } + * } + * }; + * ``` + * + * @example (relative server): + * ```ts + * const server: Server = { + * url: "/v1", + * description: "Relative server URL" + * }; + * ``` + */ +export interface Server extends Extension { + /** + * A URL to the target host. This URL supports Server Variables and MAY be relative, + * to indicate that the host location is relative to the location where the OpenAPI + * document is being served. Variable substitutions will be made when a variable + * is named in {brackets}. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-object | OpenAPI 3.0.4 Server Object - url} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-object | OpenAPI 3.0.3 Server Object - url} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-object | OpenAPI 3.0.2 Server Object - url} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-object | OpenAPI 3.0.1 Server Object - url} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-object | OpenAPI 3.0.0 Server Object - url} | + * @property `url` - Required A URL to the target host + * + * @example "https://api.example.com/v1" + * @example "https://{username}.example.com:{port}/{basePath}" + * @example "/v1" + */ + url: string; + + /** + * An optional string describing the host designated by the URL. + * CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-object | OpenAPI 3.0.4 Server Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-object | OpenAPI 3.0.3 Server Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-object | OpenAPI 3.0.2 Server Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-object | OpenAPI 3.0.1 Server Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-object | OpenAPI 3.0.0 Server Object - description} | + * @property `description` - Optional An optional string describing the host designated by the URL + * + * @example "Development server" + * @example "Production server" + */ + description?: string; + + /** + * A map between a variable name and its value. The value is used for substitution + * in the server's URL template. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-object | OpenAPI 3.0.4 Server Object - variables} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-object | OpenAPI 3.0.3 Server Object - variables} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-object | OpenAPI 3.0.2 Server Object - variables} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-object | OpenAPI 3.0.1 Server Object - variables} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-object | OpenAPI 3.0.0 Server Object - variables} | + * @property `variables` - Optional A map between a variable name and its value + * + * @example { username: { default: "demo" }, port: { default: "8080" } } + */ + variables?: Record; +} + +/** + * ----- + * Server Variable Object + * ----- + * + * An object representing a Server Variable for server URL template substitution. + * + * The Server Variable Object represents a server variable for server URL template + * substitution. It can contain an enumeration of values, a default value, and + * a description. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-variable-object | OpenAPI 3.0.4 Server Variable} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-variable-object | OpenAPI 3.0.3 Server Variable} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-variable-object | OpenAPI 3.0.2 Server Variable} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-variable-object | OpenAPI 3.0.1 Server Variable} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-variable-object | OpenAPI 3.0.0 Server Variable} | + * + * ----- + * Fields + * ----- + * + * @property `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set + * @property `default` - Required The default value to use for substitution + * @property `description` - Optional An optional description for the server variable + * @property `x-${string}` - Specification Extensions + * + * @note + * The `default` field is required. Unlike the Schema Object's default, this value MUST be provided by the consumer. + * In OpenAPI 3.0.1+, the `default` field was clarified to be the default value to use + * for substitution, and to send, if an alternate value is not supplied. + * + * ----- + * Examples + * ----- + * + * @example (simple variable): + * ```ts + * const variable: ServerVariable = { + * default: "v2", + * description: "API version" + * }; + * ``` + * + * @example (variable with enum): + * ```ts + * const variable: ServerVariable = { + * enum: ["8443", "443"], + * default: "8443", + * description: "Port number" + * }; + * ``` + * + * @example (variable with extension): + * ```ts + * const variable: ServerVariable = { + * default: "production", + * description: "Environment", + * "x-environment-type": "production" + * }; + * ``` + */ +export interface ServerVariable extends Extension { + /** + * An enumeration of string values to be used if the substitution options are from a limited set. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-variable-object | OpenAPI 3.0.4 Server Variable Object - enum} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-variable-object | OpenAPI 3.0.3 Server Variable Object - enum} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-variable-object | OpenAPI 3.0.2 Server Variable Object - enum} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-variable-object | OpenAPI 3.0.1 Server Variable Object - enum} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-variable-object | OpenAPI 3.0.0 Server Variable Object - enum} | + * @property `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set + * + * @example ["8443", "443"] + * @example ["v1", "v2", "v3"] + */ + enum?: string[]; + + /** + * The default value to use for substitution, and to send, if an alternate value is not supplied. + * Unlike the Schema Object's default, this value MUST be provided by the consumer. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-variable-object | OpenAPI 3.0.4 Server Variable Object - default} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-variable-object | OpenAPI 3.0.3 Server Variable Object - default} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-variable-object | OpenAPI 3.0.2 Server Variable Object - default} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-variable-object | OpenAPI 3.0.1 Server Variable Object - default} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-variable-object | OpenAPI 3.0.0 Server Variable Object - default} | + * @property `default` - Required The default value to use for substitution + * + * @example "demo" + * @example "8443" + * @example "v2" + */ + default: string; + + /** + * An optional description for the server variable. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#server-variable-object | OpenAPI 3.0.4 Server Variable Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#server-variable-object | OpenAPI 3.0.3 Server Variable Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#server-variable-object | OpenAPI 3.0.2 Server Variable Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#server-variable-object | OpenAPI 3.0.1 Server Variable Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#server-variable-object | OpenAPI 3.0.0 Server Variable Object - description} | + * @property `description` - Optional An optional description for the server variable + * + * @example "this value is assigned by the service provider" + * @example "Port number for the server" + */ + description?: string; +} diff --git a/3.0/spec.ts b/3.0/spec.ts new file mode 100644 index 0000000..274af52 --- /dev/null +++ b/3.0/spec.ts @@ -0,0 +1,255 @@ +import type { Components } from "./components"; +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +// Import all the major component types +import type { Info } from "./info"; +import type { Paths } from "./paths"; +import type { SecurityRequirement } from "./security"; +import type { Server } from "./servers"; +import type { Tag } from "./tags"; + +/** + * ----- + * OpenAPI Object + * ----- + * + * Root OpenAPI 3.0 Schema (OpenAPI Object) + * + * This is the root document object of the OpenAPI specification. It contains + * all the metadata about the API being described. This object is based on the + * JSON Schema Specification Wright Draft 00 and uses a predefined subset of it. + * + * The OpenAPI Object is the root of the specification document and contains + * all the information about the API, including its metadata, available paths, + * data models, security schemes, and more. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 OpenAPI Object} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 OpenAPI Object} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 OpenAPI Object} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 OpenAPI Object} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 OpenAPI Object} | + * + * ----- + * Fields + * ----- + * + * @property `openapi` - Required Specifies the OpenAPI specification version + * @property `info` - Required Provides metadata about the API + * @property `servers` - Optional An array of Server Objects + * @property `paths` - Required The available paths and operations for the API + * @property `components` - Optional An element to hold various schemas + * @property `security` - Optional A declaration of security mechanisms + * @property `tags` - Optional A list of tags used by the specification + * @property `externalDocs` - Optional Additional external documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `openapi` field is required and must be "3.0.0" for this specification. + * The `info` and `paths` fields are also required. + * + * ----- + * Examples + * ----- + * @example + * ```typescript + * const openapi: Specification = { + * openapi: "3.0.0", + * info: { + * title: "Sample Pet Store App", + * description: "This is a sample server for a pet store.", + * version: "1.0.1" + * }, + * servers: [ + * { + * url: "https://petstore.swagger.io/v2", + * description: "Petstore server" + * } + * ], + * paths: { + * "/pets": { + * get: { + * summary: "List all pets", + * responses: { + * "200": { + * description: "A list of pets", + * content: { + * "application/json": { + * schema: { + * type: "array", + * items: { $ref: "#/components/schemas/Pet" } + * } + * } + * } + * } + * } + * } + * } + * }, + * components: { + * schemas: { + * Pet: { + * type: "object", + * properties: { + * id: { type: "integer", format: "int64" }, + * name: { type: "string" }, + * tag: { type: "string" } + * } + * } + * } + * } + * } + * ``` + */ +export type Specification = { + /** + * Specifies the OpenAPI specification version being used. + * Must be "3.0.0" for this specification. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - openapi} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - openapi} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - openapi} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - openapi} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - openapi} | + * + * @property `openapi` - Required The OpenAPI specification version + */ + openapi: "3.0.0" | "3.0.1" | "3.0.2" | "3.0.3" | "3.0.4"; + + /** + * Provides metadata about the API. The metadata can be used by the clients + * if needed, and can be presented in the OpenAPI-UI for convenience. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - info} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - info} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - info} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - info} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - info} | + * + * @property `info` - Required Metadata about the API + */ + info: Info; + + /** + * An array of Server Objects, which provide connectivity information to a target server. + * If the servers property is not provided, or is an empty array, the default value + * would be a Server Object with a url value of "/". + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - servers} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - servers} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - servers} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - servers} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - servers} | + * + * @property `servers` - Optional Array of server objects + * + * @example [{ url: "https://api.example.com/v1", description: "Production server" }] + * @example [{ url: "https://staging-api.example.com/v1", description: "Staging server" }] + */ + servers?: Server[]; + + /** + * The available paths and operations for the API. This is the root of the + * Path Item Object. It does not define a path or a basePath, they are defined + * in the Paths Object. A relative path to an individual endpoint. The field + * name MUST begin with a slash. The path is appended to the basePath in order + * to construct the full URL. Path templating is allowed. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - paths} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - paths} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - paths} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - paths} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - paths} | + * + * @property `paths` - Required Available paths and operations for the API + * + * @example { "/users": { get: { ... } } } + * @example { "/users/{id}": { get: { ... } } } + */ + paths: Paths; + + /** + * An element to hold various schemas for the specification. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - components} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - components} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - components} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - components} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - components} | + * + * @property `components` - Optional Reusable objects for different aspects of the OAS + * + * @example { schemas: { User: { type: "object", properties: { ... } } } } + */ + components?: Components; + + /** + * A declaration of which security mechanisms can be used across the API. + * The list of values includes alternative security requirement objects that can be used. + * Only one of the security requirement objects need to be satisfied to authorize a request. + * Individual operations can override this definition. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - security} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - security} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - security} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - security} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - security} | + * + * @property `security` - Optional Security mechanisms for the API + * + * @example [{ "api_key": [] }] + * @example [{ "oauth2": ["read", "write"] }] + */ + security?: SecurityRequirement[]; + + /** + * A list of tags used by the specification with additional metadata. + * The order of the tags can be used to reflect on their order by the + * parsing tools. Not all tags that are used by the Operation Object must + * be declared. The tags that are not declared may be organized randomly + * or based on the tools' logic. Each tag name in the list MUST be unique. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - tags} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - tags} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - tags} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - tags} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - tags} | + * + * @property `tags` - Optional List of tags with additional metadata + * + * @example [{ name: "users", description: "User management" }] + */ + tags?: Tag[]; + + /** + * Additional external documentation. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#openapi-object | OpenAPI 3.0.4 Specification - externalDocs} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#openapi-object | OpenAPI 3.0.3 Specification - externalDocs} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#openapi-object | OpenAPI 3.0.2 Specification - externalDocs} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#openapi-object | OpenAPI 3.0.1 Specification - externalDocs} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#openapi-object | OpenAPI 3.0.0 Specification - externalDocs} | + * + * @property `externalDocs` - Optional Additional external documentation + * + * @example { description: "Find out more about our API", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; +} & Extension; diff --git a/3.0/status.ts b/3.0/status.ts new file mode 100644 index 0000000..dd1f491 --- /dev/null +++ b/3.0/status.ts @@ -0,0 +1,999 @@ +import type { Response } from "./paths"; + +/** + * Swagger 2.0 Valid HTTP Status Codes + * + * Enumerates individual HTTP status codes (as keys) plus the special `"default"` key, + * per the IANA HTTP Status Code Registry. JSDoc reason phrases and references mirror + * the registry entries. See also RFC 9110 (HTTP Semantics) section mappings. + * + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA: HTTP Status Code Registry} + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html | RFC 9110: HTTP Semantics} + */ +export interface ResponsesMap { + //#region Family Codes + + /** 1xx — Informational + * + * Indicates that the request was received and the server is continuing to process it. + * + * Used for provisional responses that indicate the server has received the request and is continuing to process it. These responses are typically used for status updates during long-running operations or to indicate that the server is ready to receive additional data. + * + * The client should continue waiting for the final response. These are provisional responses and the client should not consider the request complete until receiving a final status code. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "1xx"?: Response; + + /** 2xx — Success + * + * Indicates that the request was successfully received, understood, and accepted. + * + * Used for successful operations where the request was processed successfully and the response contains the requested data or indicates successful completion of the operation. + * + * The operation completed successfully. The response body typically contains the requested data or confirmation of the successful operation. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "2xx"?: Response; + + /** 3xx — Redirection + * + * Indicates that further action needs to be taken by the client to complete the request. + * + * Used when the client needs to take additional action to complete the request, such as following a redirect, providing authentication, or accessing the resource at a different location. + * + * The client needs to take additional action to complete the request. This may involve following a redirect, providing authentication, or accessing the resource at a different location. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "3xx"?: Response; + + /** 4xx — Client Error + * + * Indicates that the request contains bad syntax or cannot be fulfilled by the server. + * + * Used when the client has sent an invalid request, such as malformed syntax, invalid parameters, authentication failures, or requests for non-existent resources. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "4xx"?: Response; + + /** 5xx — Server Error + * + * Indicates that the server failed to fulfill a valid request. + * + * Used when the server encounters an error while processing a valid request, such as internal server errors, service unavailability, or gateway timeouts. + * + * The server encountered an error while processing the request. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "5xx"?: Response; + + //#endregion + + //#region 1xx — Informational + + /** 100 Continue + * + * Indicates that the initial part of the request has been received and the client should continue with the request. + * + * The server has received the request headers and the client should proceed to send the request body. + * + * Used in scenarios where the client needs to send a large request body and wants to confirm the server is ready to receive it before sending the data. Commonly used with `Expect: 100-continue` header for file uploads, API requests with large payloads, or when implementing optimistic request patterns. + * + * The server is ready to process the request and the client can proceed with sending the request body. This prevents unnecessary data transmission if the server would reject the request based on headers alone. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-100-continue | RFC 9110 §15.2.1} + */ + "100"?: Response; + + /** 101 Switching Protocols + * + * Indicates that the server is switching protocols as requested by the client. + * + * The server agrees to change the application protocol within the current connection, typically from HTTP to WebSocket or other protocols. + * + * Primarily used for WebSocket connections where the client sends an `Upgrade: websocket` header and the server responds with 101 to establish the WebSocket connection. Also used for HTTP/2 upgrades, Server-Sent Events (SSE), or other protocol switching scenarios. + * + * The connection will continue using a different protocol. The response headers will contain the new protocol information, and subsequent communication will use the upgraded protocol. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-101-switching-protocols | RFC 9110 §15.2.2} + */ + "101"?: Response; + + /** 102 Processing + * + * Indicates that the server has received and is processing the request, but no response is available yet. + * + * The server has accepted the request and is processing it, but the processing is taking longer than normal and the client should continue waiting. + * + * Primarily used in WebDAV (Web Distributed Authoring and Versioning) environments for long-running operations like file uploads, batch operations, or complex data processing. Helps prevent client timeouts during extended processing periods. + * + * The request is being processed and the client should continue waiting. This prevents timeout issues during long-running operations and provides feedback that the server is actively working on the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2518 | RFC 2518 (WebDAV)} + */ + "102"?: Response; + + /** 103 Early Hints + * + * Provides early hints about the response that will be sent, allowing the client to start processing before the full response is ready. + * + * The server is sending preliminary information about the response headers and resources that will be needed, enabling the client to start optimization processes early. + * + * Used for performance optimization, particularly in web applications where the server can hint about resources (CSS, JavaScript, fonts) that will be needed for the final response. Allows browsers to start preloading resources before the main response is ready, significantly improving perceived performance. + * + * The client can start preparing for the response based on the hints provided. This is especially valuable for web applications where resource preloading can improve user experience. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8297 | RFC 8297} + */ + "103"?: Response; + + /** 104 Upload Resumption Supported — TEMPORARY + * + * Indicates that the server supports resumable uploads for the requested resource. + * + * The server is indicating that it can handle interrupted uploads and allows the client to resume uploading from where it left off. + * + * Used in file upload scenarios where large files might be interrupted due to network issues, browser crashes, or other problems. Enables clients to resume uploads without starting over, improving reliability for large file transfers and reducing bandwidth waste. + * + * The client can implement resumable upload logic, typically using range requests or specialized upload protocols. This is particularly valuable for mobile applications and unreliable network conditions. + * + * @note Temporary registration; see IANA entry for current status/expiry. + * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-resumable-upload-05 | draft-ietf-httpbis-resumable-upload-05} + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA registry} + */ + "104"?: Response; + + //#endregion + + //#region 2xx — Success + + /** 200 OK + * + * Indicates that the request has succeeded and the response contains the requested data. + * + * The request was processed successfully and the response body contains the requested resource or data. + * + * The most common success response for GET requests, API endpoints that return data, and successful operations. Used for retrieving resources, executing queries, and any operation that completes successfully with data to return. + * + * The operation completed successfully and the response body contains the requested information. This is the standard success response for most API operations. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok | RFC 9110 §15.3.1} + */ + "200"?: Response; + + /** 201 Created + * + * Indicates that the request has succeeded and a new resource has been created as a result. + * + * The request was processed successfully and resulted in the creation of a new resource. The response typically includes the location of the newly created resource. + * + * Used for POST requests that create new resources (users, posts, files, etc.). The response should include a `Location` header pointing to the newly created resource. Common in REST APIs for resource creation operations. + * + * A new resource was successfully created and the response contains information about the created resource, typically including its ID and location. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-201-created | RFC 9110 §15.3.2} + */ + "201"?: Response; + + /** 202 Accepted + * + * Indicates that the request has been accepted for processing, but the processing has not been completed. + * + * The request was valid and accepted, but the server will process it asynchronously. The processing may or may not eventually succeed. + * + * Used for asynchronous operations like background jobs, batch processing, email sending, or any operation that takes time to complete. The client should not assume the operation succeeded based on this response alone. + * + * The request was accepted and is being processed asynchronously. The client should check the status separately or wait for a callback/webhook to know the final result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted | RFC 9110 §15.3.3} + */ + "202"?: Response; + + /** 203 Non-Authoritative Information + * + * Indicates that the request was successful, but the information returned is from a transformed or cached version of the original resource. + * + * The response is successful but the data may have been modified by a transforming proxy or cache, and may not be the authoritative version. + * + * Used when responses come from caches, proxies, or transformation services where the data might be slightly different from the original. Common in CDN scenarios or when data is processed through middleware. + * + * The request succeeded but the response data may not be the most current or authoritative version. The client should be aware that the data might be cached or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-203-non-authoritative-informat | RFC 9110 §15.3.4} + */ + "203"?: Response; + + /** 204 No Content + * + * Indicates that the request has succeeded but there is no content to return in the response body. + * + * The request was processed successfully but the response body is intentionally empty. The client should not expect any content. + * + * Used for DELETE operations, PUT requests that don't return data, or any operation where success is indicated by the absence of content. Common in REST APIs for operations that modify state without returning data. + * + * The operation completed successfully but no data is returned. The client should not attempt to parse a response body. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-204-no-content | RFC 9110 §15.3.5} + */ + "204"?: Response; + + /** 205 Reset Content + * + * Indicates that the request has succeeded and the client should reset the document view that caused the request to be sent. + * + * The request was processed successfully and the client should clear any form data or reset the user interface state. + * + * Used in web applications where form submissions should clear the form after successful processing, or when the client needs to reset its state. Common in form handling and user interface operations. + * + * The operation succeeded and the client should reset its current state, typically clearing forms or resetting the user interface. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-205-reset-content | RFC 9110 §15.3.6} + */ + "205"?: Response; + + /** 206 Partial Content + * + * Indicates that the server is delivering only part of the resource due to a range request. + * + * The request included a Range header and the server is returning only the requested portion of the resource, along with information about the range delivered. + * + * Used for resumable downloads, video streaming, large file transfers, and any scenario where the client requests a specific portion of a resource. Enables efficient handling of large files and interrupted downloads. + * + * The response contains only a portion of the requested resource. The client should expect partial content and may need to make additional requests for the complete resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-206-partial-content | RFC 9110 §15.3.7} + */ + "206"?: Response; + + /** 207 Multi-Status + * + * Indicates that multiple independent operations might have been performed, and the status of each operation is reported in the response body. + * + * The response contains multiple status codes for different operations, typically in XML format with individual operation results. + * + * Used in WebDAV environments for batch operations, bulk file operations, or any scenario where multiple independent operations are performed in a single request. Common in file management systems and collaborative editing platforms. + * + * Multiple operations were attempted and the response contains the status of each individual operation. The client should parse the response body to determine which operations succeeded or failed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "207"?: Response; + + /** 208 Already Reported + * + * Indicates that the members of a DAV binding have already been enumerated in a previous response to this request, and are not being included again. + * + * Used in WebDAV to avoid repeating the same information in a multi-status response when the same binding has already been reported. + * + * Used in WebDAV environments to optimize responses by avoiding duplicate information in multi-status responses. Helps reduce response size and improve performance in complex file system operations. + * + * The information for this binding has already been reported in a previous part of the response. The client should not expect additional information for this specific binding. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "208"?: Response; + + /** 226 IM Used + * + * Indicates that the server has fulfilled a request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance. + * + * The response represents the result of applying instance manipulations (like delta encoding) to the current resource instance. + * + * Used in scenarios involving delta encoding, instance manipulations, or when the response represents a transformed version of the resource. Common in content delivery networks and systems that optimize data transmission. + * + * The response contains a manipulated version of the resource, typically optimized for transmission. The client should be aware that the data has been processed or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc3229 | RFC 3229} + */ + "226"?: Response; + + //#endregion + + //#region 3xx — Redirection + + /** 300 Multiple Choices + * + * Indicates that the request has multiple possible responses and the client should choose one. + * + * The server has multiple representations of the requested resource and the client must choose which one to use. + * + * Used when content negotiation results in multiple valid options, such as different formats (JSON, XML, HTML) or different languages. The response typically includes a list of available options with their characteristics. + * + * The client should examine the available options and make a choice, typically by sending another request with more specific preferences or headers. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-300-multiple-choices | RFC 9110 §15.4.1} + */ + "300"?: Response; + + /** 301 Moved Permanently + * + * Indicates that the requested resource has been permanently moved to a new location. + * + * The resource has been permanently relocated and all future requests should be directed to the new URL provided in the Location header. + * + * Used when resources are permanently relocated, such as when changing domain names, restructuring URLs, or moving content to new locations. Browsers and clients should update their bookmarks and caches. + * + * The resource has moved permanently and the client should update all references to use the new URL. Search engines and caches should update their indexes. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-301-moved-permanently | RFC 9110 §15.4.2} + */ + "301"?: Response; + + /** 302 Found + * + * Indicates that the requested resource has been temporarily moved to a different location. + * + * The resource is temporarily available at a different URL, but the original URL should continue to be used for future requests. + * + * Used for temporary redirects such as maintenance pages, temporary content moves, or when the resource is temporarily unavailable at the original location. The original URL remains valid. + * + * The resource is temporarily at a different location. The client should follow the redirect but continue using the original URL for future requests. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-302-found | RFC 9110 §15.4.3} + */ + "302"?: Response; + + /** 303 See Other + * + * Indicates that the response to the request can be found at a different URL and should be retrieved using a GET request. + * + * The request was processed but the response is available at a different location, and the client should use GET to retrieve it. + * + * Used in POST-redirect-GET patterns, form submissions that redirect to a results page, or when the response to a POST request should be retrieved via GET. Common in web applications for avoiding duplicate form submissions. + * + * The client should make a GET request to the provided URL to retrieve the response. This prevents duplicate submissions and provides a clean URL for the result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-303-see-other | RFC 9110 §15.4.4} + */ + "303"?: Response; + + /** 304 Not Modified + * + * Indicates that the resource has not been modified since the last request, so the cached version can be used. + * + * The resource has not changed since the last request, and the client can use its cached version. No response body is included. + * + * Used for caching optimization when the client sends conditional headers (If-Modified-Since, If-None-Match). Reduces bandwidth usage and improves performance by avoiding unnecessary data transfer. + * + * The resource has not changed and the client should use its cached version. This is an optimization response that saves bandwidth and improves performance. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-304-not-modified | RFC 9110 §15.4.5} + */ + "304"?: Response; + + /** 305 Use Proxy + * + * Indicates that the requested resource must be accessed through the proxy specified in the Location header. + * + * The client must use the specified proxy to access the resource. This response is rarely used in modern web applications. + * + * Used in corporate environments or specific network configurations where resources must be accessed through a particular proxy server. Mostly deprecated in modern web development. + * + * The client should use the specified proxy to access the resource. This is rarely encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy | RFC 9110 §15.4.6} + */ + "305"?: Response; + + /** 306 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code was previously used but is now reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-306-unused | RFC 9110 §15.4.7} + */ + "306"?: Response; + + /** 307 Temporary Redirect + * + * Indicates that the requested resource has been temporarily moved to a different location, and the request method should be preserved. + * + * The resource is temporarily available at a different URL, and the client should repeat the request using the same method to the new location. + * + * Used for temporary redirects where the HTTP method (POST, PUT, DELETE) should be preserved. Common in API versioning, temporary maintenance, or when resources are temporarily relocated. + * + * The resource is temporarily at a different location and the client should repeat the same request method to the new URL. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-307-temporary-redirect | RFC 9110 §15.4.8} + */ + "307"?: Response; + + /** 308 Permanent Redirect + * + * Indicates that the requested resource has been permanently moved to a different location, and the request method should be preserved. + * + * The resource has been permanently relocated and the client should use the new URL for all future requests, preserving the original HTTP method. + * + * Used for permanent redirects where the HTTP method should be preserved, such as when moving APIs to new endpoints or restructuring resource URLs. Common in API versioning and permanent relocations. + * + * The resource has moved permanently and the client should update all references to use the new URL while preserving the original HTTP method. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-308-permanent-redirect | RFC 9110 §15.4.9} + */ + "308"?: Response; + + //#endregion + + //#region 4xx — Client Error + + /** 400 Bad Request + * + * Indicates that the server cannot process the request due to a client error. + * + * The request syntax is invalid, malformed, or contains incorrect parameters that the server cannot understand or process. + * + * Used for validation errors, malformed JSON, missing required fields, invalid parameter values, or any client-side error that prevents the server from processing the request. Common in API validation scenarios. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request | RFC 9110 §15.5.1} + */ + "400"?: Response; + + /** 401 Unauthorized + * + * Indicates that the request requires authentication and the client has not provided valid credentials. + * + * The request lacks valid authentication credentials or the provided credentials are invalid, expired, or insufficient. + * + * Used when authentication is required but not provided, when login credentials are invalid, or when the authentication token has expired. Common in protected API endpoints and user authentication flows. + * + * The client needs to authenticate before accessing the resource. The response should include authentication challenge headers (WWW-Authenticate) indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized | RFC 9110 §15.5.2} + */ + "401"?: Response; + + /** 402 Payment Required + * + * Indicates that the request requires payment before it can be processed. + * + * The request cannot be fulfilled because payment is required. This status code is reserved for future use in digital payment systems. + * + * Used in payment-required scenarios, subscription services, or when access to a resource requires payment. Common in freemium models, paid API access, or premium content services. + * + * The client needs to provide payment information or complete a payment process before accessing the resource. The response should include information about how to make the payment. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required | RFC 9110 §15.5.3} + */ + "402"?: Response; + + /** 403 Forbidden + * + * Indicates that the server understood the request but refuses to authorize it. + * + * The client is authenticated but does not have permission to access the requested resource or perform the requested action. + * + * Used when the user is logged in but lacks the necessary permissions, when access is restricted based on user roles, or when the resource is not accessible to the current user. Common in authorization and access control scenarios. + * + * The client is authenticated but not authorized to access the resource. The client should not retry the request without additional permissions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden | RFC 9110 §15.5.4} + */ + "403"?: Response; + + /** 404 Not Found + * + * Indicates that the requested resource could not be found on the server. + * + * The server cannot find the requested resource at the specified URL, or the resource does not exist. + * + * Used when a resource doesn't exist, when the URL is incorrect, or when the requested item has been deleted. Common in web applications for missing pages, deleted content, or non-existent API endpoints. + * + * The requested resource does not exist. The client should verify the URL or check if the resource has been moved or deleted. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found | RFC 9110 §15.5.5} + */ + "404"?: Response; + + /** 405 Method Not Allowed + * + * Indicates that the HTTP method used in the request is not allowed for the requested resource. + * + * The resource exists but the HTTP method (GET, POST, PUT, DELETE, etc.) is not supported for this particular resource. + * + * Used when a resource only supports certain HTTP methods, such as a read-only endpoint that doesn't allow POST requests, or when the method is not implemented for the specific resource. Common in REST API design. + * + * The HTTP method is not allowed for this resource. The response should include an Allow header listing the permitted methods. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-405-method-not-allowed | RFC 9110 §15.5.6} + */ + "405"?: Response; + + /** 406 Not Acceptable + * + * Indicates that the server cannot produce a response matching the client's Accept headers. + * + * The server cannot generate a response in any of the formats requested by the client's Accept headers. + * + * Used when the client requests a specific content type (JSON, XML, HTML) that the server cannot provide, or when content negotiation fails. Common in API versioning and content type mismatches. + * + * The server cannot provide the requested content type. The client should check the Accept headers or request a different format. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable | RFC 9110 §15.5.7} + */ + "406"?: Response; + + /** 407 Proxy Authentication Required + * + * Indicates that the client must authenticate with the proxy server before the request can be processed. + * + * The proxy server requires authentication before it will forward the request to the destination server. + * + * Used in corporate environments or networks where proxy authentication is required. Common in enterprise networks, VPN connections, or when accessing resources through authenticated proxies. + * + * The client needs to authenticate with the proxy server. The response should include Proxy-Authenticate headers indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-req | RFC 9110 §15.5.8} + */ + "407"?: Response; + + /** 408 Request Timeout + * + * Indicates that the server timed out while waiting for the request from the client. + * + * The server did not receive a complete request within the time it was prepared to wait. + * + * Used when the client takes too long to send the complete request, when network issues cause delays, or when the server has a timeout policy for request processing. Common in slow network conditions or when clients fail to send complete requests. + * + * The request timed out and the client should retry the request. The client may need to optimize the request or check network connectivity. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-408-request-timeout | RFC 9110 §15.5.9} + */ + "408"?: Response; + + /** 409 Conflict + * + * Indicates that the request conflicts with the current state of the resource. + * + * The request cannot be completed due to a conflict with the current state of the resource, such as a version mismatch or concurrent modification. + * + * Used when trying to create a resource that already exists, when there's a version conflict in concurrent editing, or when the request conflicts with business rules. Common in collaborative editing, version control, and resource creation scenarios. + * + * The request conflicts with the current state of the resource. The client should resolve the conflict before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict | RFC 9110 §15.5.10} + */ + "409"?: Response; + + /** 410 Gone + * + * Indicates that the requested resource is no longer available and will not be available again. + * + * The resource has been permanently removed and will not be restored. This is different from 404, which indicates the resource was never found. + * + * Used when content has been permanently deleted, when resources have been removed and will not be restored, or when temporary content has expired. Common in content management systems and temporary resource scenarios. + * + * The resource has been permanently removed and will not be available again. The client should not retry the request and should update any references to this resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-410-gone | RFC 9110 §15.5.11} + */ + "410"?: Response; + + /** 411 Length Required + * + * Indicates that the server requires a Content-Length header in the request. + * + * The server cannot process the request without knowing the exact length of the request body. + * + * Used when the server needs to know the exact size of the request body before processing, such as for file uploads, large data transfers, or when implementing specific security measures. Common in file upload scenarios and certain API endpoints. + * + * The client must include a Content-Length header in the request. The client should retry the request with the proper Content-Length header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-411-length-required | RFC 9110 §15.5.12} + */ + "411"?: Response; + + /** 412 Precondition Failed + * + * Indicates that one or more preconditions in the request headers were not met. + * + * The server cannot meet the conditions specified in the request headers, such as If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-Since. + * + * Used in conditional requests where the client specifies conditions that must be met, such as version checking, cache validation, or optimistic concurrency control. Common in collaborative editing and caching scenarios. + * + * The preconditions in the request were not met. The client should check the conditions and retry the request with updated preconditions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-412-precondition-failed | RFC 9110 §15.5.13} + */ + "412"?: Response; + + /** 413 Content Too Large + * + * Indicates that the request payload is too large for the server to process. + * + * The request body exceeds the server's maximum allowed size limit. + * + * Used when file uploads exceed size limits, when request bodies are too large for processing, or when the server has configured size restrictions. Common in file upload scenarios and API rate limiting. + * + * The request payload is too large. The client should reduce the size of the request body or split it into smaller chunks. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-413-content-too-large | RFC 9110 §15.5.14} + */ + "413"?: Response; + + /** 414 URI Too Long + * + * Indicates that the URI provided in the request is too long for the server to process. + * + * The URL exceeds the server's maximum allowed length limit. + * + * Used when URLs are too long due to excessive query parameters, when GET requests contain too much data in the URL, or when the server has configured URI length restrictions. Common in search APIs and parameter-heavy requests. + * + * The URI is too long. The client should shorten the URL or use POST instead of GET for large amounts of data. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-414-uri-too-long | RFC 9110 §15.5.15} + */ + "414"?: Response; + + /** 415 Unsupported Media Type + * + * Indicates that the server cannot process the request because the media type is not supported. + * + * The server cannot process the request body because the Content-Type is not supported or recognized. + * + * Used when the client sends data in an unsupported format, when the server only accepts specific content types, or when there's a mismatch between the expected and actual content type. Common in API endpoints with strict content type requirements. + * + * The content type is not supported. The client should check the API documentation for supported content types and retry with the correct Content-Type header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type | RFC 9110 §15.5.16} + */ + "415"?: Response; + + /** 416 Range Not Satisfiable + * + * Indicates that the server cannot satisfy the range request specified in the Range header. + * + * The requested range is not valid for the resource, either because the range is beyond the resource size or the resource doesn't support range requests. + * + * Used when range requests are invalid, when the requested range exceeds the resource size, or when the resource doesn't support partial content requests. Common in file download scenarios and media streaming. + * + * The range request is not satisfiable. The client should check the range specification or request the full resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-416-range-not-satisfiable | RFC 9110 §15.5.17} + */ + "416"?: Response; + + /** 417 Expectation Failed + * + * Indicates that the server cannot meet the requirements of the Expect header. + * + * The server cannot fulfill the expectations specified in the Expect header, typically when the server cannot handle the 100-continue expectation. + * + * Used when the server cannot handle the Expect: 100-continue header, when the server doesn't support the expected behavior, or when there's a mismatch between client expectations and server capabilities. Common in HTTP/1.1 implementations. + * + * The server cannot meet the expectations in the request. The client should retry without the Expect header or adjust the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-417-expectation-failed | RFC 9110 §15.5.18} + */ + "417"?: Response; + + /** 418 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code is reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-418-unused | RFC 9110 §15.5.19} + */ + "418"?: Response; + + /** 421 Misdirected Request + * + * Indicates that the request was directed to a server that is not able to produce a response. + * + * The request was sent to a server that cannot handle it, typically due to HTTP/2 connection reuse issues or server configuration problems. + * + * Used in HTTP/2 environments when a request is sent to the wrong server due to connection reuse, when there are server configuration issues, or when the request cannot be processed by the current server instance. Common in load balancing scenarios. + * + * The request was sent to the wrong server. The client should retry the request, which may be routed to a different server. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-request | RFC 9110 §15.5.20} + */ + "421"?: Response; + + /** 422 Unprocessable Content + * + * Indicates that the request is well-formed but contains semantic errors that prevent processing. + * + * The request syntax is correct but the server cannot process the request due to semantic errors, such as validation failures or business rule violations. + * + * Used for validation errors, business rule violations, or when the request is syntactically correct but logically invalid. Common in API validation scenarios where the request format is correct but the data is invalid. + * + * The request is well-formed but contains semantic errors. The client should fix the data and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content | RFC 9110 §15.5.21} + */ + "422"?: Response; + + /** 423 Locked + * + * Indicates that the requested resource is locked and cannot be modified. + * + * The resource is locked by another process or user and cannot be accessed or modified at this time. + * + * Used in WebDAV environments for file locking, collaborative editing scenarios, or when resources are temporarily locked for maintenance. Common in document management systems and collaborative editing platforms. + * + * The resource is locked and cannot be accessed. The client should wait and retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "423"?: Response; + + /** 424 Failed Dependency + * + * Indicates that the request failed because it depended on another request that also failed. + * + * The request cannot be completed because it depends on another operation that failed, typically in batch or multi-part operations. + * + * Used in WebDAV environments for batch operations where one operation depends on another, or in complex workflows where operations have dependencies. Common in file management systems and collaborative editing scenarios. + * + * The request failed due to a dependency failure. The client should check the dependencies and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "424"?: Response; + + /** 425 Too Early + * + * Indicates that the server is unwilling to process the request because it might be replayed. + * + * The server is concerned that the request might be replayed and is unwilling to process it at this time, typically due to timing or security concerns. + * + * Used in scenarios where request replay is a security concern, such as in early data scenarios or when the server needs to prevent replay attacks. Common in security-sensitive applications and protocols. + * + * The server is unwilling to process the request due to replay concerns. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8470 | RFC 8470} + */ + "425"?: Response; + + /** 426 Upgrade Required + * + * Indicates that the server requires the client to upgrade to a different protocol. + * + * The server requires the client to use a different protocol version or upgrade to a newer version to access the resource. + * + * Used when the server requires protocol upgrades, when the client is using an outdated protocol version, or when the server only supports newer protocol versions. Common in API versioning and protocol migration scenarios. + * + * The client must upgrade to a different protocol version. The response should include upgrade information. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-426-upgrade-required | RFC 9110 §15.5.22} + */ + "426"?: Response; + + /** 428 Precondition Required + * + * Indicates that the server requires the request to include certain preconditions. + * + * The server requires the client to include specific preconditions in the request headers before it will process the request. + * + * Used when the server requires specific preconditions for security or consistency reasons, such as requiring If-Match headers for optimistic concurrency control or other conditional headers. Common in collaborative editing and version control scenarios. + * + * The server requires specific preconditions. The client should include the required preconditions and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "428"?: Response; + + /** 429 Too Many Requests + * + * Indicates that the client has sent too many requests in a given time period and should slow down. + * + * The client has exceeded the rate limit and the server is refusing to process additional requests until the rate limit resets. + * + * Used for rate limiting, API throttling, and preventing abuse. Common in API endpoints that need to control request frequency, prevent spam, or manage resource usage. Often includes retry-after headers. + * + * The client has exceeded the rate limit and should slow down. The client should wait before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "429"?: Response; + + /** 431 Request Header Fields Too Large + * + * Indicates that the server is unwilling to process the request because the header fields are too large. + * + * The request headers exceed the server's maximum allowed size limit. + * + * Used when request headers are too large, when there are too many headers, or when individual headers exceed size limits. Common in scenarios with large authentication tokens or excessive header data. + * + * The request headers are too large. The client should reduce the size of the headers and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "431"?: Response; + + /** 451 Unavailable For Legal Reasons + * + * Indicates that the requested resource is unavailable due to legal reasons. + * + * The resource is not available due to legal restrictions, such as censorship, court orders, or regulatory requirements. + * + * Used when content is blocked due to legal restrictions, when resources are unavailable in certain jurisdictions, or when there are regulatory compliance issues. Common in content delivery networks and international services. + * + * The resource is unavailable due to legal restrictions. The client should not retry the request as it will not be available. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc7725 | RFC 7725} + */ + "451"?: Response; + + //#endregion + + //#region 5xx — Server Error + + /** 500 Internal Server Error + * + * Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. + * + * The server encountered an internal error or exception that prevented it from processing the request successfully. + * + * Used for server-side errors, unhandled exceptions, database connection failures, or any unexpected server-side issue. Common in applications when there are bugs, configuration issues, or resource problems. + * + * The server encountered an internal error. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error | RFC 9110 §15.6.1} + */ + "500"?: Response; + + /** 501 Not Implemented + * + * Indicates that the server does not support the functionality required to fulfill the request. + * + * The server does not recognize the request method or lacks the ability to fulfill the request. + * + * Used when the server doesn't support the requested HTTP method, when functionality is not implemented, or when the server cannot handle the request. Common in API development when endpoints are not yet implemented. + * + * The server does not support the requested functionality. The client should check the API documentation for supported methods and features. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-501-not-implemented | RFC 9110 §15.6.2} + */ + "501"?: Response; + + /** 502 Bad Gateway + * + * Indicates that the server, while acting as a gateway or proxy, received an invalid response from an upstream server. + * + * The server acting as a gateway or proxy received an invalid response from the upstream server it was trying to access. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server returns an invalid response or is unreachable. Common in microservices architectures and distributed systems. + * + * The gateway received an invalid response from the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway | RFC 9110 §15.6.3} + */ + "502"?: Response; + + /** 503 Service Unavailable + * + * Indicates that the server is temporarily unable to handle the request due to maintenance or overload. + * + * The server is temporarily unavailable, typically due to maintenance, overload, or temporary resource constraints. + * + * Used during server maintenance, when the server is overloaded, when there are temporary resource issues, or when the service is temporarily down. Common in high-traffic scenarios and planned maintenance windows. + * + * The server is temporarily unavailable. The client should retry the request later, often with exponential backoff. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable | RFC 9110 §15.6.4} + */ + "503"?: Response; + + /** 504 Gateway Timeout + * + * Indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server. + * + * The gateway or proxy server timed out while waiting for a response from the upstream server. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server takes too long to respond. Common in microservices architectures where services have different response times. + * + * The gateway timed out waiting for the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-504-gateway-timeout | RFC 9110 §15.6.5} + */ + "504"?: Response; + + /** 505 HTTP Version Not Supported + * + * Indicates that the server does not support the HTTP protocol version used in the request. + * + * The server does not support the HTTP protocol version specified in the request. + * + * Used when the client uses an unsupported HTTP version, when the server only supports specific HTTP versions, or when there are protocol version mismatches. Common in legacy systems and protocol migration scenarios. + * + * The server does not support the HTTP version used in the request. The client should use a supported HTTP version. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-supporte | RFC 9110 §15.6.6} + */ + "505"?: Response; + + /** 506 Variant Also Negotiates + * + * Indicates that the server has an internal configuration error in which the chosen variant resource is configured to engage in transparent content negotiation. + * + * The server has a configuration error where the selected variant resource is configured to engage in transparent content negotiation, creating a negotiation loop. + * + * Used in content negotiation scenarios where there's a configuration error causing negotiation loops. Common in complex content delivery systems and advanced HTTP implementations. + * + * The server has a configuration error in content negotiation. The client should contact the server administrator. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2295 | RFC 2295} + */ + "506"?: Response; + + /** 507 Insufficient Storage + * + * Indicates that the server is unable to store the representation needed to complete the request. + * + * The server cannot store the representation required to complete the request, typically due to storage space limitations. + * + * Used in WebDAV environments when there's insufficient storage space, when the server cannot allocate storage for the request, or when storage quotas are exceeded. Common in file management systems and collaborative editing platforms. + * + * The server cannot store the required representation. The client should check storage availability and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "507"?: Response; + + /** 508 Loop Detected + * + * Indicates that the server detected an infinite loop while processing the request. + * + * The server detected an infinite loop in the request processing, typically in WebDAV operations. + * + * Used in WebDAV environments when there are infinite loops in request processing, when there are circular references in operations, or when the server detects recursive operations. Common in file management systems and collaborative editing scenarios. + * + * The server detected an infinite loop. The client should check the request for circular references and retry. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "508"?: Response; + + /** 510 Not Extended — OBSOLETED + * + * This status code is obsolete and should not be used in modern implementations. + * + * This status code was used for HTTP extensions but is now obsolete and should not be used. + * + * Not used in modern web applications. This code is obsolete and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2774 | RFC 2774 (Historic)} + * @see {@link https://datatracker.ietf.org/doc/status-change-http-experiments-to-historic/ | IETF: Status change of HTTP experiments to Historic} + */ + "510"?: Response; + + /** 511 Network Authentication Required + * + * Indicates that the client needs to authenticate to gain network access. + * + * The client must authenticate with the network before it can access the requested resource. + * + * Used in captive portal scenarios, public Wi-Fi networks, or when network-level authentication is required. Common in public networks, hotels, airports, and other locations where network access requires authentication. + * + * The client needs to authenticate with the network. The client should follow the authentication process provided by the network. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "511"?: Response; + + //#endregion + + /** default — The default response for all codes not covered individually. */ + default?: Response; +} diff --git a/3.0/tags.ts b/3.0/tags.ts new file mode 100644 index 0000000..18bef16 --- /dev/null +++ b/3.0/tags.ts @@ -0,0 +1,111 @@ +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; + +/** + * ----- + * Tag Object + * ----- + * + * Adds metadata to a single tag that is used by the Tag Object. + * It is not mandatory to have a Tag Object per tag used there. + * + * Tags provide a way to organize and categorize API operations, making it easier + * for developers to understand and navigate the API. They are commonly used to + * group operations by resource type, functionality, or any other logical division. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#tag-object | OpenAPI 3.0.4 Tag} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#tag-object | OpenAPI 3.0.3 Tag} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#tag-object | OpenAPI 3.0.2 Tag} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#tag-object | OpenAPI 3.0.1 Tag} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#tag-object | OpenAPI 3.0.0 Tag} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The name of the tag + * @property `description` - Optional A short description for the tag + * @property `externalDocs` - Optional Additional external documentation for this tag + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple tag): + * ```ts + * const tag: Tag = { + * name: "users", + * description: "User management operations" + * }; + * ``` + * + * @example (tag with external documentation): + * ```ts + * const tag: Tag = { + * name: "pets", + * description: "Pet store operations", + * externalDocs: { + * description: "Find out more about pet management", + * url: "https://example.com/docs/pets" + * } + * }; + * ``` + */ +export interface Tag extends Extension { + /** + * The name of the tag. This field is required. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#tag-object | OpenAPI 3.0.4 Tag Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#tag-object | OpenAPI 3.0.3 Tag Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#tag-object | OpenAPI 3.0.2 Tag Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#tag-object | OpenAPI 3.0.1 Tag Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#tag-object | OpenAPI 3.0.0 Tag Object - name} | + * @property `name` - Required The name of the tag + * + * @example "users" + * @example "pets" + * @example "authentication" + */ + name: string; + + /** + * A short description for the tag. CommonMark syntax MAY be used for rich text representation. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#tag-object | OpenAPI 3.0.4 Tag Object - description} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#tag-object | OpenAPI 3.0.3 Tag Object - description} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#tag-object | OpenAPI 3.0.2 Tag Object - description} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#tag-object | OpenAPI 3.0.1 Tag Object - description} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#tag-object | OpenAPI 3.0.0 Tag Object - description} | + * @property `description` - Optional A short description for the tag + * + * @example "User management operations" + * @example "Pet store operations" + */ + description?: string; + + /** + * Additional external documentation for this tag. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#tag-object | OpenAPI 3.0.4 Tag Object - externalDocs} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#tag-object | OpenAPI 3.0.3 Tag Object - externalDocs} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#tag-object | OpenAPI 3.0.2 Tag Object - externalDocs} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#tag-object | OpenAPI 3.0.1 Tag Object - externalDocs} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#tag-object | OpenAPI 3.0.0 Tag Object - externalDocs} | + * @property `externalDocs` - Optional Additional external documentation for this tag + * + * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } + */ + externalDocs?: ExternalDocumentation; +} diff --git a/3.0/xml.ts b/3.0/xml.ts new file mode 100644 index 0000000..d5eeef8 --- /dev/null +++ b/3.0/xml.ts @@ -0,0 +1,136 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * XML Object + * ----- + * + * A metadata object that allows for more fine-tuned XML model definitions. + * When using arrays, XML element names are not inferred (for singular/plural forms) + * and the name property should be used to add that information. + * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Optional Replaces the name of the element/attribute used for the described schema property + * @property `namespace` - Optional The URL of the namespace definition + * @property `prefix` - Optional The prefix to be used for the name + * @property `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element + * @property `wrapped` - Optional MAY be used only for an array definition + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. + * + * ----- + * Examples + * ----- + * + * @example (simple XML): + * ```ts + * const xml: XML = { + * name: "animal" + * }; + * ``` + */ +export interface XML extends Extension { + /** + * Replaces the name of the element/attribute used for the described schema property. + * When defined within items, it will affect the name of the individual XML elements within the list. + * When defined alongside type being array (outside the items), it will affect the wrapping element + * and only if wrapped is true. If wrapped is false, it will affect the items within the array. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object - name} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object - name} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object - name} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object - name} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object - name} | + * @property `name` - Optional Replaces the name of the element/attribute used for the described schema property + * + * @example "animal" + * @example "item" + */ + name?: string; + + /** + * The URL of the namespace definition. Value SHOULD be in the form of a URL. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object - namespace} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object - namespace} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object - namespace} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object - namespace} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object - namespace} | + * @property `namespace` - Optional The URL of the namespace definition + * + * @example "http://example.com/schema" + * @example "http://www.w3.org/XML/1998/namespace" + */ + namespace?: string; + + /** + * The prefix to be used for the name. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object - prefix} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object - prefix} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object - prefix} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object - prefix} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object - prefix} | + * @property `prefix` - Optional The prefix to be used for the name + * + * @example "xs" + * @example "ns" + */ + prefix?: string; + + /** + * Declares whether the property definition translates to an attribute instead of an element. + * Default value is false. + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object - attribute} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object - attribute} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object - attribute} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object - attribute} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object - attribute} | + * @property `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element + * + * @example true + * @example false + */ + attribute?: boolean; + + /** + * MAY be used only for an array definition. Signifies whether the array is wrapped (for example, + * ) or unwrapped (). Default value is false. + * The definition takes effect only when defined alongside type being array (outside the items). + * * + * | Version | Reference | + * |---|-----| + * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object - wrapped} | + * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object - wrapped} | + * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object - wrapped} | + * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object - wrapped} | + * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object - wrapped} | + * @property `wrapped` - Optional MAY be used only for an array definition. Signifies whether the array is wrapped + * + * @example true + * @example false + */ + wrapped?: boolean; +} diff --git a/3.1.x/components.ts b/3.1.x/components.ts deleted file mode 100644 index 71e3daa..0000000 --- a/3.1.x/components.ts +++ /dev/null @@ -1,134 +0,0 @@ -import type { Extension } from "./extensions" -import type { Reference } from "./references" -import type { Schema } from "./schema" -import type { Response, Parameter, Example, RequestBody, Header, Link, Callback, PathItemObject } from "./paths" -import type { SecurityScheme } from "./security" - -/** - * ----- - * Components Object - * ----- - * - * Holds a set of reusable objects for different aspects of the OAS. All objects defined - * within the components object will have no effect on the API unless they are explicitly - * referenced from properties outside the components object. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#components-object | OpenAPI 3.1.0 Components Object} | - * - * ----- - * Fields - * ----- - * - * @key `schemas` - An object to hold reusable Schema Objects - * @key `responses` - An object to hold reusable Response Objects - * @key `parameters` - An object to hold reusable Parameter Objects - * @key `examples` - An object to hold reusable Example Objects - * @key `requestBodies` - An object to hold reusable Request Body Objects - * @key `headers` - An object to hold reusable Header Objects - * @key `securitySchemes` - An object to hold reusable Security Scheme Objects - * @key `links` - An object to hold reusable Link Objects - * @key `callbacks` - An object to hold reusable Callback Objects - * @key `pathItems` - An object to hold reusable Path Item Objects - * @key `x-${string}` - Specification Extensions - * - * @note - * All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. - * - * ----- - * Examples - * ----- - * - * @example (simple components): - * ```ts - * const components: Components = { - * schemas: { - * User: { - * type: "object", - * properties: { - * id: { type: "integer", format: "int64" }, - * name: { type: "string" } - * } - * } - * }, - * responses: { - * NotFound: { - * description: "Resource not found" - * } - * } - * }; - * ``` - */ -export interface Components extends Extension { - /** - * An object to hold reusable Schema Objects. - * - * @example { User: { type: "object", properties: { id: { type: "integer" } } } } - */ - schemas?: Record - - /** - * An object to hold reusable Response Objects. - * - * @example { NotFound: { description: "Resource not found" } } - */ - responses?: Record - - /** - * An object to hold reusable Parameter Objects. - * - * @example { UserId: { name: "userId", in: "path", required: true, schema: { type: "string" } } } - */ - parameters?: Record - - /** - * An object to hold reusable Example Objects. - * - * @example { UserExample: { value: { id: 1, name: "John Doe" } } } - */ - examples?: Record - - /** - * An object to hold reusable Request Body Objects. - * - * @example { UserRequestBody: { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } } - */ - requestBodies?: Record - - /** - * An object to hold reusable Header Objects. - * - * @example { RateLimit: { description: "Rate limit per hour", schema: { type: "integer" } } } - */ - headers?: Record - - /** - * An object to hold reusable Security Scheme Objects. - * - * @example { ApiKeyAuth: { type: "apiKey", in: "header", name: "X-API-KEY" } } - */ - securitySchemes?: Record - - /** - * An object to hold reusable Link Objects. - * - * @example { UserOrders: { operationId: "getOrdersByUserId", parameters: { userId: "$response.body#/id" } } } - */ - links?: Record - - /** - * An object to hold reusable Callback Objects. - * - * @example { UserCreatedCallback: { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "User created event" } } } } } - */ - callbacks?: Record - - /** - * An object to hold reusable Path Item Objects. - * - * @example { UserPath: { get: { summary: "Get user by ID" } } } - */ - pathItems?: Record -} diff --git a/3.1.x/data-types/array.ts b/3.1.x/data-types/array.ts deleted file mode 100644 index 9f168df..0000000 --- a/3.1.x/data-types/array.ts +++ /dev/null @@ -1,202 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Array Schema - * ----- - * - * A schema for array values. Includes array-specific validation properties - * that are only valid when `type: "array"` is specified. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | - * - * ----- - * Fields - * ----- - * - * @key `type: "array"` - Required The type identifier for array schemas - * @key `items` - Optional Schema for array items - * @key `prefixItems` - Optional Schema for array items at specific positions - * @key `contains` - Optional Schema that array must contain at least one item matching - * @key `minContains` - Optional Minimum number of items that must match contains - * @key `maxContains` - Optional Maximum number of items that must match contains - * @key `minItems` - Optional Minimum number of items in the array - * @key `maxItems` - Optional Maximum number of items in the array - * @key `uniqueItems` - Optional Whether array items must be unique - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * All validation properties are optional. The `type` field must be "array". - * - * ----- - * Examples - * ----- - * - * @example (basic array): - * ```ts - * const arraySchema: ArraySchema = { - * type: "array", - * items: { type: "string" } - * }; - * ``` - * - * @example (array with validation): - * ```ts - * const arraySchema: ArraySchema = { - * type: "array", - * items: { type: "string" }, - * minItems: 1, - * maxItems: 10, - * uniqueItems: true - * }; - * ``` - * - * @example (array with prefixItems): - * ```ts - * const arraySchema: ArraySchema = { - * type: "array", - * prefixItems: [ - * { type: "string" }, - * { type: "number" } - * ] - * }; - * ``` - * - * @example (array with contains): - * ```ts - * const arraySchema: ArraySchema = { - * type: "array", - * items: { type: "string" }, - * contains: { type: "string", enum: ["admin"] }, - * minContains: 1 - * }; - * ``` - */ -export interface ArraySchema extends Extension { - /** - * The type identifier for array schemas. - * Must be "array". - */ - type: "array" - - /** - * The schema for array items. - * All items in the array must conform to this schema. - * - * Example: `{ type: "string" }` - */ - items?: unknown - - /** - * The schema for array items at specific positions. - * Items at position i must conform to the schema at index i. - * - * Example: `[{ type: "string" }, { type: "number" }]` - */ - prefixItems?: unknown[] - - /** - * The schema that the array must contain at least one item matching. - * At least one item in the array must conform to this schema. - * - * Example: `{ type: "string", enum: ["admin"] }` - */ - contains?: unknown - - /** - * The minimum number of items that must match the contains schema. - * Must be a non-negative integer. - * - * Example: `1` - */ - minContains?: number - - /** - * The maximum number of items that must match the contains schema. - * Must be a non-negative integer. - * - * Example: `5` - */ - maxContains?: number - - /** - * The minimum number of items in the array. - * Must be a non-negative integer. - * - * Example: `1` - */ - minItems?: number - - /** - * The maximum number of items in the array. - * Must be a non-negative integer. - * - * Example: `10` - */ - maxItems?: number - - /** - * Whether array items must be unique. - * If true, all items in the array must be unique. - * - * Example: `true` - */ - uniqueItems?: boolean - - /** - * An array of allowed values for the array. - * The value must be one of the values in this array. - * - * Example: `[["a", "b"], ["c", "d"]]` - */ - enum?: unknown[] - - /** - * A single allowed value for the array. - * The value must be exactly this value. - * - * Example: `["a", "b"]` - */ - const?: unknown - - /** - * An array of example values for the array. - * These are for documentation purposes only. - * - * Example: `[["a", "b"], ["c", "d"]]` - */ - examples?: unknown[] - - /** - * The default value for the array. - * This value will be used if no value is provided. - * - * Example: `[]` - */ - default?: unknown[] - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"User Tags"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"Array of user tags"` - */ - description?: string -} diff --git a/3.1.x/data-types/boolean.ts b/3.1.x/data-types/boolean.ts deleted file mode 100644 index c5ffe79..0000000 --- a/3.1.x/data-types/boolean.ts +++ /dev/null @@ -1,121 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Boolean Schema - * ----- - * - * A schema for boolean values. Includes common validation properties - * that are only valid when `type: "boolean"` is specified. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | - * - * ----- - * Fields - * ----- - * - * @key `type: "boolean"` - Required The type identifier for boolean schemas - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * All validation properties are optional. The `type` field must be "boolean". - * - * ----- - * Examples - * ----- - * - * @example (basic boolean): - * ```ts - * const booleanSchema: BooleanSchema = { - * type: "boolean" - * }; - * ``` - * - * @example (boolean with default): - * ```ts - * const booleanSchema: BooleanSchema = { - * type: "boolean", - * default: false - * }; - * ``` - * - * @example (boolean with enum): - * ```ts - * const booleanSchema: BooleanSchema = { - * type: "boolean", - * enum: [true, false] - * }; - * ``` - * - * @example (boolean with const): - * ```ts - * const booleanSchema: BooleanSchema = { - * type: "boolean", - * const: true - * }; - * ``` - */ -export interface BooleanSchema extends Extension { - /** - * The type identifier for boolean schemas. - * Must be "boolean". - */ - type: "boolean" - - /** - * An array of allowed values for the boolean. - * The value must be one of the values in this array. - * - * Example: `[true, false]` - */ - enum?: boolean[] - - /** - * A single allowed value for the boolean. - * The value must be exactly this value. - * - * Example: `true` - */ - const?: boolean - - /** - * An array of example values for the boolean. - * These are for documentation purposes only. - * - * Example: `[true, false]` - */ - examples?: boolean[] - - /** - * The default value for the boolean. - * This value will be used if no value is provided. - * - * Example: `false` - */ - default?: boolean - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"Is Active"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"Whether the user is active"` - */ - description?: string -} diff --git a/3.1.x/data-types/composition.ts b/3.1.x/data-types/composition.ts deleted file mode 100644 index 02623f6..0000000 --- a/3.1.x/data-types/composition.ts +++ /dev/null @@ -1,189 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Composition Schema - * ----- - * - * A schema that uses composition keywords (allOf, anyOf, oneOf, not). - * These keywords are mutually exclusive with $ref, but otherwise can - * appear with any validation keywords. This schema type supports - * advanced JSON Schema 2020-12 features like conditional schemas. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} | - * - * ----- - * Fields - * ----- - * - * @key `allOf` - Optional Array of schemas that must all be satisfied - * @key `anyOf` - Optional Array of schemas where at least one must be satisfied - * @key `oneOf` - Optional Array of schemas where exactly one must be satisfied - * @key `not` - Optional Schema that must not be satisfied - * @key `if` - Optional Schema for conditional validation - * @key `then` - Optional Schema to apply if if condition is met - * @key `else` - Optional Schema to apply if if condition is not met - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * Composition keywords are mutually exclusive with $ref. At least one composition - * keyword must be present. The `if`/`then`/`else` keywords work together for - * conditional validation. - * - * ----- - * Examples - * ----- - * - * @example (allOf composition): - * ```ts - * const compositionSchema: CompositionSchema = { - * allOf: [ - * { type: "object", properties: { name: { type: "string" } } }, - * { type: "object", properties: { age: { type: "number" } } } - * ] - * }; - * ``` - * - * @example (anyOf composition): - * ```ts - * const compositionSchema: CompositionSchema = { - * anyOf: [ - * { type: "string" }, - * { type: "number" } - * ] - * }; - * ``` - * - * @example (oneOf composition): - * ```ts - * const compositionSchema: CompositionSchema = { - * oneOf: [ - * { type: "string", enum: ["active"] }, - * { type: "string", enum: ["inactive"] } - * ] - * }; - * ``` - * - * @example (conditional schema): - * ```ts - * const compositionSchema: CompositionSchema = { - * if: { type: "object", properties: { type: { const: "user" } } }, - * then: { type: "object", properties: { name: { type: "string" } } }, - * else: { type: "object", properties: { id: { type: "string" } } } - * }; - * ``` - */ -export interface CompositionSchema extends Extension { - /** - * An array of schemas that must all be satisfied. - * The value must conform to all schemas in the array. - * - * Example: `[{ type: "object" }, { properties: { name: { type: "string" } } }]` - */ - allOf?: unknown[] - - /** - * An array of schemas where at least one must be satisfied. - * The value must conform to at least one schema in the array. - * - * Example: `[{ type: "string" }, { type: "number" }]` - */ - anyOf?: unknown[] - - /** - * An array of schemas where exactly one must be satisfied. - * The value must conform to exactly one schema in the array. - * - * Example: `[{ type: "string" }, { type: "number" }]` - */ - oneOf?: unknown[] - - /** - * A schema that must not be satisfied. - * The value must not conform to this schema. - * - * Example: `{ type: "string" }` - */ - not?: unknown - - /** - * A schema for conditional validation. - * Used with `then` and `else` for conditional logic. - * - * Example: `{ type: "object", properties: { type: { const: "user" } } }` - */ - if?: unknown - - /** - * A schema to apply if the `if` condition is met. - * The value must conform to this schema if the `if` schema is satisfied. - * - * Example: `{ type: "object", properties: { name: { type: "string" } } }` - */ - then?: unknown - - /** - * A schema to apply if the `if` condition is not met. - * The value must conform to this schema if the `if` schema is not satisfied. - * - * Example: `{ type: "object", properties: { id: { type: "string" } } }` - */ - else?: unknown - - /** - * An array of allowed values. - * The value must be one of the values in this array. - * - * Example: `["active", "inactive"]` - */ - enum?: unknown[] - - /** - * A single allowed value. - * The value must be exactly this value. - * - * Example: `"active"` - */ - const?: unknown - - /** - * An array of example values. - * These are for documentation purposes only. - * - * Example: `["example1", "example2"]` - */ - examples?: unknown[] - - /** - * The default value. - * This value will be used if no value is provided. - * - * Example: `"default"` - */ - default?: unknown - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"Composed Schema"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"A schema composed of multiple schemas"` - */ - description?: string -} diff --git a/3.1.x/data-types/index.ts b/3.1.x/data-types/index.ts deleted file mode 100644 index 95891fd..0000000 --- a/3.1.x/data-types/index.ts +++ /dev/null @@ -1,8 +0,0 @@ -export type { ReferenceSchema } from "./reference" -export type { StringSchema } from "./string" -export type { NumberSchema } from "./number" -export type { IntegerSchema } from "./integer" -export type { BooleanSchema } from "./boolean" -export type { ArraySchema } from "./array" -export type { ObjectSchema } from "./object" -export type { CompositionSchema } from "./composition" diff --git a/3.1.x/data-types/integer.ts b/3.1.x/data-types/integer.ts deleted file mode 100644 index 4c66614..0000000 --- a/3.1.x/data-types/integer.ts +++ /dev/null @@ -1,178 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Integer Schema - * ----- - * - * A schema for integer values. Includes integer-specific validation properties - * that are only valid when `type: "integer"` is specified. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | - * - * ----- - * Fields - * ----- - * - * @key `type: "integer"` - Required The type identifier for integer schemas - * @key `format` - Optional The format of the integer - * @key `multipleOf` - Optional Integer must be a multiple of this value - * @key `maximum` - Optional Maximum value (inclusive) - * @key `minimum` - Optional Minimum value (inclusive) - * @key `exclusiveMaximum` - Optional Maximum value (exclusive) - * @key `exclusiveMinimum` - Optional Minimum value (exclusive) - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * All validation properties are optional. The `type` field must be "integer". - * - * ----- - * Examples - * ----- - * - * @example (basic integer): - * ```ts - * const integerSchema: IntegerSchema = { - * type: "integer" - * }; - * ``` - * - * @example (integer with format and validation): - * ```ts - * const integerSchema: IntegerSchema = { - * type: "integer", - * format: "int32", - * minimum: 0, - * maximum: 100 - * }; - * ``` - * - * @example (integer with multipleOf): - * ```ts - * const integerSchema: IntegerSchema = { - * type: "integer", - * multipleOf: 5 - * }; - * ``` - * - * @example (integer with exclusive bounds): - * ```ts - * const integerSchema: IntegerSchema = { - * type: "integer", - * exclusiveMinimum: 0, - * exclusiveMaximum: 100 - * }; - * ``` - */ -export interface IntegerSchema extends Extension { - /** - * The type identifier for integer schemas. - * Must be "integer". - */ - type: "integer" - - /** - * The format of the integer. - * See OpenAPI 3.1.x Data Type Formats for further details. - * - * Example: `"int32"`, `"int64"` - */ - format?: string - - /** - * The integer must be a multiple of this value. - * Must be a positive integer. - * - * Example: `5` - */ - multipleOf?: number - - /** - * The maximum value of the integer (inclusive). - * The integer must be less than or equal to this value. - * - * Example: `100` - */ - maximum?: number - - /** - * The minimum value of the integer (inclusive). - * The integer must be greater than or equal to this value. - * - * Example: `0` - */ - minimum?: number - - /** - * The maximum value of the integer (exclusive). - * The integer must be less than this value. - * - * Example: `100` - */ - exclusiveMaximum?: number - - /** - * The minimum value of the integer (exclusive). - * The integer must be greater than this value. - * - * Example: `0` - */ - exclusiveMinimum?: number - - /** - * An array of allowed values for the integer. - * The value must be one of the values in this array. - * - * Example: `[1, 2, 3, 4, 5]` - */ - enum?: number[] - - /** - * A single allowed value for the integer. - * The value must be exactly this value. - * - * Example: `42` - */ - const?: number - - /** - * An array of example values for the integer. - * These are for documentation purposes only. - * - * Example: `[1, 2, 3]` - */ - examples?: number[] - - /** - * The default value for the integer. - * This value will be used if no value is provided. - * - * Example: `0` - */ - default?: number - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"User ID"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"The unique identifier of the user"` - */ - description?: string -} diff --git a/3.1.x/data-types/number.ts b/3.1.x/data-types/number.ts deleted file mode 100644 index cc1f04d..0000000 --- a/3.1.x/data-types/number.ts +++ /dev/null @@ -1,178 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Number Schema - * ----- - * - * A schema for number values. Includes number-specific validation properties - * that are only valid when `type: "number"` is specified. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | - * - * ----- - * Fields - * ----- - * - * @key `type: "number"` - Required The type identifier for number schemas - * @key `format` - Optional The format of the number - * @key `multipleOf` - Optional Number must be a multiple of this value - * @key `maximum` - Optional Maximum value (inclusive) - * @key `minimum` - Optional Minimum value (inclusive) - * @key `exclusiveMaximum` - Optional Maximum value (exclusive) - * @key `exclusiveMinimum` - Optional Minimum value (exclusive) - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * All validation properties are optional. The `type` field must be "number". - * - * ----- - * Examples - * ----- - * - * @example (basic number): - * ```ts - * const numberSchema: NumberSchema = { - * type: "number" - * }; - * ``` - * - * @example (number with format and validation): - * ```ts - * const numberSchema: NumberSchema = { - * type: "number", - * format: "float", - * minimum: 0, - * maximum: 100 - * }; - * ``` - * - * @example (number with multipleOf): - * ```ts - * const numberSchema: NumberSchema = { - * type: "number", - * multipleOf: 0.5 - * }; - * ``` - * - * @example (number with exclusive bounds): - * ```ts - * const numberSchema: NumberSchema = { - * type: "number", - * exclusiveMinimum: 0, - * exclusiveMaximum: 100 - * }; - * ``` - */ -export interface NumberSchema extends Extension { - /** - * The type identifier for number schemas. - * Must be "number". - */ - type: "number" - - /** - * The format of the number. - * See OpenAPI 3.1.x Data Type Formats for further details. - * - * Example: `"float"`, `"double"` - */ - format?: string - - /** - * The number must be a multiple of this value. - * Must be a positive number. - * - * Example: `0.5` - */ - multipleOf?: number - - /** - * The maximum value of the number (inclusive). - * The number must be less than or equal to this value. - * - * Example: `100` - */ - maximum?: number - - /** - * The minimum value of the number (inclusive). - * The number must be greater than or equal to this value. - * - * Example: `0` - */ - minimum?: number - - /** - * The maximum value of the number (exclusive). - * The number must be less than this value. - * - * Example: `100` - */ - exclusiveMaximum?: number - - /** - * The minimum value of the number (exclusive). - * The number must be greater than this value. - * - * Example: `0` - */ - exclusiveMinimum?: number - - /** - * An array of allowed values for the number. - * The value must be one of the values in this array. - * - * Example: `[1, 2, 3, 4, 5]` - */ - enum?: number[] - - /** - * A single allowed value for the number. - * The value must be exactly this value. - * - * Example: `42` - */ - const?: number - - /** - * An array of example values for the number. - * These are for documentation purposes only. - * - * Example: `[1.5, 2.7, 3.14]` - */ - examples?: number[] - - /** - * The default value for the number. - * This value will be used if no value is provided. - * - * Example: `0` - */ - default?: number - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"Price"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"The price of the item"` - */ - description?: string -} diff --git a/3.1.x/data-types/object.ts b/3.1.x/data-types/object.ts deleted file mode 100644 index ba7c4ae..0000000 --- a/3.1.x/data-types/object.ts +++ /dev/null @@ -1,217 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * Object Schema - * ----- - * - * A schema for object values. Includes object-specific validation properties - * that are only valid when `type: "object"` is specified. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | - * - * ----- - * Fields - * ----- - * - * @key `type: "object"` - Required The type identifier for object schemas - * @key `properties` - Optional Map of property names to their schemas - * @key `required` - Optional Array of required property names - * @key `additionalProperties` - Optional Schema for additional properties - * @key `patternProperties` - Optional Map of regex patterns to schemas - * @key `propertyNames` - Optional Schema for property names - * @key `minProperties` - Optional Minimum number of properties - * @key `maxProperties` - Optional Maximum number of properties - * @key `dependentRequired` - Optional Map of property names to arrays of required properties - * @key `dependentSchemas` - Optional Map of property names to schemas - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * All validation properties are optional. The `type` field must be "object". - * - * ----- - * Examples - * ----- - * - * @example (basic object): - * ```ts - * const objectSchema: ObjectSchema = { - * type: "object", - * properties: { - * name: { type: "string" }, - * age: { type: "number" } - * } - * }; - * ``` - * - * @example (object with required properties): - * ```ts - * const objectSchema: ObjectSchema = { - * type: "object", - * properties: { - * name: { type: "string" }, - * age: { type: "number" } - * }, - * required: ["name"] - * }; - * ``` - * - * @example (object with additionalProperties): - * ```ts - * const objectSchema: ObjectSchema = { - * type: "object", - * properties: { - * name: { type: "string" } - * }, - * additionalProperties: { type: "string" } - * }; - * ``` - * - * @example (object with patternProperties): - * ```ts - * const objectSchema: ObjectSchema = { - * type: "object", - * patternProperties: { - * "^S_": { type: "string" } - * } - * }; - * ``` - */ -export interface ObjectSchema extends Extension { - /** - * The type identifier for object schemas. - * Must be "object". - */ - type: "object" - - /** - * A map of property names to their schemas. - * Each property in the object must conform to its corresponding schema. - * - * Example: `{ name: { type: "string" }, age: { type: "number" } }` - */ - properties?: Record - - /** - * An array of required property names. - * These properties must be present in the object. - * - * Example: `["name", "email"]` - */ - required?: string[] - - /** - * The schema for additional properties not defined in properties. - * If false, no additional properties are allowed. - * If true, any additional properties are allowed. - * If a schema, additional properties must conform to this schema. - * - * Example: `{ type: "string" }` or `false` or `true` - */ - additionalProperties?: unknown | boolean - - /** - * A map of regex patterns to schemas. - * Properties whose names match a pattern must conform to the corresponding schema. - * - * Example: `{ "^S_": { type: "string" } }` - */ - patternProperties?: Record - - /** - * The schema for property names. - * All property names in the object must conform to this schema. - * - * Example: `{ type: "string", pattern: "^[A-Za-z][A-Za-z0-9]*$" }` - */ - propertyNames?: unknown - - /** - * The minimum number of properties in the object. - * Must be a non-negative integer. - * - * Example: `1` - */ - minProperties?: number - - /** - * The maximum number of properties in the object. - * Must be a non-negative integer. - * - * Example: `10` - */ - maxProperties?: number - - /** - * A map of property names to arrays of required properties. - * If a property is present, the properties in its array must also be present. - * - * Example: `{ credit_card: ["billing_address"] }` - */ - dependentRequired?: Record - - /** - * A map of property names to schemas. - * If a property is present, the object must conform to the corresponding schema. - * - * Example: `{ credit_card: { type: "object", properties: { number: { type: "string" } } } }` - */ - dependentSchemas?: Record - - /** - * An array of allowed values for the object. - * The value must be one of the values in this array. - * - * Example: `[{ name: "John" }, { name: "Jane" }]` - */ - enum?: Record[] - - /** - * A single allowed value for the object. - * The value must be exactly this value. - * - * Example: `{ name: "John" }` - */ - const?: Record - - /** - * An array of example values for the object. - * These are for documentation purposes only. - * - * Example: `[{ name: "John", age: 30 }]` - */ - examples?: Record[] - - /** - * The default value for the object. - * This value will be used if no value is provided. - * - * Example: `{}` - */ - default?: Record - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"User"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"A user object"` - */ - description?: string -} diff --git a/3.1.x/data-types/string.ts b/3.1.x/data-types/string.ts deleted file mode 100644 index f6dc2a2..0000000 --- a/3.1.x/data-types/string.ts +++ /dev/null @@ -1,159 +0,0 @@ -import type { Extension } from "../extensions" - -/** - * ----- - * String Schema - * ----- - * - * A schema for string values. Includes string-specific validation properties - * that are only valid when `type: "string"` is specified. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | - * - * ----- - * Fields - * ----- - * - * @key `type: "string"` - Required The type identifier for string schemas - * @key `format` - Optional The format of the string - * @key `maxLength` - Optional Maximum length of the string - * @key `minLength` - Optional Minimum length of the string - * @key `pattern` - Optional Regular expression pattern - * @key `enum` - Optional Array of allowed values - * @key `const` - Optional Single allowed value - * @key `examples` - Optional Array of example values - * @key `default` - Optional Default value - * @key `title` - Optional Short title for the schema - * @key `description` - Optional Description of the schema - * @key `x-${string}` - Specification Extensions - * - * @note - * All validation properties are optional. The `type` field must be "string". - * - * ----- - * Examples - * ----- - * - * @example (basic string): - * ```ts - * const stringSchema: StringSchema = { - * type: "string" - * }; - * ``` - * - * @example (string with format and validation): - * ```ts - * const stringSchema: StringSchema = { - * type: "string", - * format: "email", - * maxLength: 255, - * minLength: 5 - * }; - * ``` - * - * @example (string with enum): - * ```ts - * const stringSchema: StringSchema = { - * type: "string", - * enum: ["active", "inactive", "pending"] - * }; - * ``` - * - * @example (string with pattern): - * ```ts - * const stringSchema: StringSchema = { - * type: "string", - * pattern: "^[A-Za-z0-9]+$" - * }; - * ``` - */ -export interface StringSchema extends Extension { - /** - * The type identifier for string schemas. - * Must be "string". - */ - type: "string" - - /** - * The format of the string. - * See OpenAPI 3.1.x Data Type Formats for further details. - * - * Example: `"email"`, `"date-time"`, `"uuid"` - */ - format?: string - - /** - * The maximum length of the string. - * Must be a non-negative integer. - * - * Example: `255` - */ - maxLength?: number - - /** - * The minimum length of the string. - * Must be a non-negative integer. - * - * Example: `1` - */ - minLength?: number - - /** - * A regular expression pattern that the string must match. - * Should be a valid ECMA 262 regular expression. - * - * Example: `"^[A-Za-z0-9]+$"` - */ - pattern?: string - - /** - * An array of allowed values for the string. - * The value must be one of the values in this array. - * - * Example: `["active", "inactive", "pending"]` - */ - enum?: string[] - - /** - * A single allowed value for the string. - * The value must be exactly this value. - * - * Example: `"active"` - */ - const?: string - - /** - * An array of example values for the string. - * These are for documentation purposes only. - * - * Example: `["example@email.com", "test@domain.com"]` - */ - examples?: string[] - - /** - * The default value for the string. - * This value will be used if no value is provided. - * - * Example: `"default"` - */ - default?: string - - /** - * A short title for the schema. - * This is for documentation purposes only. - * - * Example: `"User Email"` - */ - title?: string - - /** - * A description of the schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"The email address of the user"` - */ - description?: string -} diff --git a/3.1.x/info.ts b/3.1.x/info.ts deleted file mode 100644 index 6cd2f02..0000000 --- a/3.1.x/info.ts +++ /dev/null @@ -1,263 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * Info Object - * ----- - * - * The object provides metadata about the API. The metadata MAY be used by tooling - * as required. The object may be extended with Specification Extensions. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#info-object | OpenAPI 3.1.1 Info Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#info-object | OpenAPI 3.1.0 Info Object} | - * - * ----- - * Fields - * ----- - * - * @key `title` - Required The title of the API - * @key `summary` - Optional A short summary of the API - * @key `description` - Optional A description of the API - * @key `termsOfService` - Optional A URL to the Terms of Service for the API - * @key `contact` - Optional The contact information for the exposed API - * @key `license` - Optional The license information for the exposed API - * @key `version` - Required The version of the OpenAPI document - * @key `x-${string}` - Specification Extensions - * - * @note - * The `title` and `version` fields are required. - * - * ----- - * Examples - * ----- - * - * @example (minimal info): - * ```ts - * const info: Info = { - * title: "Pet Store API", - * version: "1.0.0" - * }; - * ``` - * - * @example (complete info): - * ```ts - * const info: Info = { - * title: "Pet Store API", - * summary: "A sample API that uses a petstore as an example", - * description: "This is a sample server Petstore server.", - * termsOfService: "http://example.com/terms/", - * contact: { - * name: "API Support", - * url: "http://www.example.com/support", - * email: "support@example.com" - * }, - * license: { - * name: "Apache 2.0", - * url: "https://www.apache.org/licenses/LICENSE-2.0.html" - * }, - * version: "1.0.0" - * }; - * ``` - */ -export interface Info extends Extension { - /** - * The title of the API. This field is required. - * - * @example "Pet Store API" - * @example "User Management API" - */ - title: string - - /** - * A short summary of the API. - * - * @example "A sample API that uses a petstore as an example" - * @example "API for managing users and their data" - */ - summary?: string - - /** - * A description of the API. CommonMark syntax MAY be used for rich text representation. - * - * @example "This is a sample server Petstore server." - * @example "This API provides endpoints for user management, authentication, and data operations." - */ - description?: string - - /** - * A URL to the Terms of Service for the API. MUST be in the format of a URL. - * - * @example "http://example.com/terms/" - * @example "https://www.example.com/terms-of-service" - */ - termsOfService?: string - - /** - * The contact information for the exposed API. - * - * @example { name: "API Support", email: "support@example.com" } - */ - contact?: Contact - - /** - * The license information for the exposed API. - * - * @example { name: "Apache 2.0", url: "https://www.apache.org/licenses/LICENSE-2.0.html" } - */ - license?: License - - /** - * The version of the OpenAPI document. This field is required. - * - * @example "1.0.0" - * @example "2.1.3" - */ - version: string -} - -/** - * ----- - * Contact Object - * ----- - * - * Contact information for the exposed API. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#contact-object | OpenAPI 3.1.1 Contact Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#contact-object | OpenAPI 3.1.0 Contact Object} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Optional The identifying name of the contact person/organization - * @key `url` - Optional The URL pointing to the contact information - * @key `email` - Optional The email address of the contact person/organization - * @key `x-${string}` - Specification Extensions - * - * @note - * All fields are optional. - * - * ----- - * Examples - * ----- - * - * @example (simple contact): - * ```ts - * const contact: Contact = { - * name: "API Support", - * email: "support@example.com" - * }; - * ``` - * - * @example (complete contact): - * ```ts - * const contact: Contact = { - * name: "API Support", - * url: "http://www.example.com/support", - * email: "support@example.com" - * }; - * ``` - */ -export interface Contact extends Extension { - /** - * The identifying name of the contact person/organization. - * - * @example "API Support" - * @example "Development Team" - */ - name?: string - - /** - * The URL pointing to the contact information. MUST be in the format of a URL. - * - * @example "http://www.example.com/support" - * @example "https://example.com/contact" - */ - url?: string - - /** - * The email address of the contact person/organization. MUST be in the format of an email address. - * - * @example "support@example.com" - * @example "dev@example.com" - */ - email?: string -} - -/** - * ----- - * License Object - * ----- - * - * License information for the exposed API. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#license-object | OpenAPI 3.1.1 License Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#license-object | OpenAPI 3.1.0 License Object} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Required The license name used for the API - * @key `identifier` - Optional An SPDX license expression for the API - * @key `url` - Optional A URL to the license used for the API - * @key `x-${string}` - Specification Extensions - * - * @note - * The `name` field is required. Either `identifier` or `url` should be specified. - * - * ----- - * Examples - * ----- - * - * @example (with URL): - * ```ts - * const license: License = { - * name: "Apache 2.0", - * url: "https://www.apache.org/licenses/LICENSE-2.0.html" - * }; - * ``` - * - * @example (with identifier): - * ```ts - * const license: License = { - * name: "Apache 2.0", - * identifier: "Apache-2.0" - * }; - * ``` - */ -export interface License extends Extension { - /** - * The license name used for the API. This field is required. - * - * @example "Apache 2.0" - * @example "MIT" - * @example "GPL-3.0" - */ - name: string - - /** - * An SPDX license expression for the API. The `identifier` field is mutually - * exclusive of the `url` field. - * - * @example "Apache-2.0" - * @example "MIT" - * @example "GPL-3.0" - */ - identifier?: string - - /** - * A URL to the license used for the API. MUST be in the format of a URL. - * The `url` field is mutually exclusive of the `identifier` field. - * - * @example "https://www.apache.org/licenses/LICENSE-2.0.html" - * @example "https://opensource.org/licenses/MIT" - */ - url?: string -} diff --git a/3.1.x/paths.ts b/3.1.x/paths.ts deleted file mode 100644 index 1331f23..0000000 --- a/3.1.x/paths.ts +++ /dev/null @@ -1,1446 +0,0 @@ -import type { Extension } from "./extensions" -import type { Reference } from "./references" -import type { Server } from "./servers" -import type { SecurityRequirement } from "./security" -import type { Schema } from "./schema" -import type { ExternalDocumentation } from "./externalDocs" - -/** - * ----- - * Paths Object - * ----- - * - * Holds the relative paths to the individual endpoints and their operations. - * The path is appended to the URL from the Server Object in order to construct - * the full URL. The Paths may be empty, due to ACL constraints. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#paths-object | OpenAPI 3.1.1 Paths Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#paths-object | OpenAPI 3.1.0 Paths Object} | - * - * ----- - * Fields - * ----- - * - * @key `/{path}` - A relative path to an individual endpoint - * @key `x-${string}` - Specification Extensions - * - * @note - * The path keys must start with `/` and can contain path parameters in `{brackets}`. - * - * ----- - * Examples - * ----- - * - * @example (simple paths): - * ```ts - * const paths: Paths = { - * "/pets": { - * "get": { - * "summary": "List all pets", - * "responses": { - * "200": { - * "description": "A list of pets" - * } - * } - * } - * } - * }; - * ``` - */ -export type Paths = Record - -/** - * ----- - * Path Item Object - * ----- - * - * Describes the operations available on a single path. A Path Item MAY be empty, - * due to ACL constraints. The path itself is still exposed to the documentation - * viewer but they will not know which operations and parameters are available. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#path-item-object | OpenAPI 3.1.1 Path Item Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#path-item-object | OpenAPI 3.1.0 Path Item Object} | - * - * ----- - * Fields - * ----- - * - * @key `summary` - Optional An optional, string summary, intended to apply to all operations in this path - * @key `description` - Optional An optional, string description, intended to apply to all operations in this path - * @key `get` - Optional A definition of a GET operation on this path - * @key `put` - Optional A definition of a PUT operation on this path - * @key `post` - Optional A definition of a POST operation on this path - * @key `delete` - Optional A definition of a DELETE operation on this path - * @key `options` - Optional A definition of an OPTIONS operation on this path - * @key `head` - Optional A definition of a HEAD operation on this path - * @key `patch` - Optional A definition of a PATCH operation on this path - * @key `trace` - Optional A definition of a TRACE operation on this path - * @key `servers` - Optional An alternative server array to service all operations in this path - * @key `parameters` - Optional A list of parameters that are applicable for all the operations described under this path - * @key `x-${string}` - Specification Extensions - * - * @note - * All fields are optional. The HTTP methods are mutually exclusive. - * - * ----- - * Examples - * ----- - * - * @example (simple path item): - * ```ts - * const pathItem: PathItemObject = { - * "get": { - * "summary": "List all pets", - * "responses": { - * "200": { - * "description": "A list of pets" - * } - * } - * } - * }; - * ``` - */ -export interface PathItemObject extends Extension { - /** - * An optional, string summary, intended to apply to all operations in this path. - * - * @example "Pet operations" - * @example "User management" - */ - summary?: string - - /** - * An optional, string description, intended to apply to all operations in this path. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "Operations related to pet management" - * @example "All user-related operations" - */ - description?: string - - /** - * A definition of a GET operation on this path. - */ - get?: Operation - - /** - * A definition of a PUT operation on this path. - */ - put?: Operation - - /** - * A definition of a POST operation on this path. - */ - post?: Operation - - /** - * A definition of a DELETE operation on this path. - */ - delete?: Operation - - /** - * A definition of an OPTIONS operation on this path. - */ - options?: Operation - - /** - * A definition of a HEAD operation on this path. - */ - head?: Operation - - /** - * A definition of a PATCH operation on this path. - */ - patch?: Operation - - /** - * A definition of a TRACE operation on this path. - */ - trace?: Operation - - /** - * An alternative server array to service all operations in this path. - * - * @example [{ url: "https://api.example.com/v1" }] - */ - servers?: Server[] - - /** - * A list of parameters that are applicable for all the operations described under - * this path. These parameters can be overridden at the operation level, but cannot - * be removed there. The list MUST NOT include duplicated parameters. A unique - * parameter is defined by a combination of a name and location. - * - * @example [{ name: "id", in: "path", required: true, schema: { type: "string" } }] - */ - parameters?: (Parameter | Reference)[] -} - -/** - * ----- - * Operation Object - * ----- - * - * Describes a single API operation on a path. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#operation-object | OpenAPI 3.1.1 Operation Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#operation-object | OpenAPI 3.1.0 Operation Object} | - * - * ----- - * Fields - * ----- - * - * @key `tags` - Optional A list of tags for API documentation control - * @key `summary` - Optional A short summary of what the operation does - * @key `description` - Optional A verbose explanation of the operation behavior - * @key `externalDocs` - Optional Additional external documentation for this operation - * @key `operationId` - Optional Unique string used to identify the operation - * @key `parameters` - Optional A list of parameters that are applicable for this operation - * @key `requestBody` - Optional The request body applicable for this operation - * @key `responses` - Required The list of possible responses as they are returned from executing this operation - * @key `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation - * @key `deprecated` - Optional Declares this operation to be deprecated - * @key `security` - Optional A declaration of which security mechanisms can be used for this operation - * @key `servers` - Optional An alternative server array to service this operation - * @key `x-${string}` - Specification Extensions - * - * @note - * The `responses` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple operation): - * ```ts - * const operation: Operation = { - * "summary": "List all pets", - * "responses": { - * "200": { - * "description": "A list of pets" - * } - * } - * }; - * ``` - */ -export interface Operation extends Extension { - /** - * A list of tags for API documentation control. Tags can be used for logical - * grouping of operations by resources or any other qualifier. - * - * @example ["pets", "list"] - * @example ["users", "authentication"] - */ - tags?: string[] - - /** - * A short summary of what the operation does. - * - * @example "List all pets" - * @example "Create a new user" - */ - summary?: string - - /** - * A verbose explanation of the operation behavior. CommonMark syntax MAY be used - * for rich text representation. - * - * @example "Returns all pets from the system that the user has access to" - * @example "Creates a new user account with the provided information" - */ - description?: string - - /** - * Additional external documentation for this operation. - * - * @example { description: "Find out more about pet operations", url: "https://example.com/docs/pets" } - */ - externalDocs?: ExternalDocumentation - - /** - * Unique string used to identify the operation. The id MUST be unique among all - * operations described in the API. The operationId value is case-sensitive. - * - * @example "listPets" - * @example "createUser" - */ - operationId?: string - - /** - * A list of parameters that are applicable for this operation. If a parameter - * is already defined at the Path Item, the new definition will override it but - * can never remove it. The list MUST NOT include duplicated parameters. - * - * @example [{ name: "limit", in: "query", schema: { type: "integer" } }] - */ - parameters?: (Parameter | Reference)[] - - /** - * The request body applicable for this operation. The requestBody is only supported - * in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined - * semantics for request bodies. - * - * @example { description: "Pet to add to the store", content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } } - */ - requestBody?: RequestBody | Reference - - /** - * The list of possible responses as they are returned from executing this operation. - * This field is required. - * - * @example { "200": { description: "A list of pets" }, "default": { description: "Unexpected error" } } - */ - responses: Responses - - /** - * A map of possible out-of band callbacks related to the parent operation. The key - * is a unique identifier for the Callback Object. Each value in the map is a - * Callback Object that describes a request that may be initiated by the API - * provider and the expected responses. - * - * @example { "myCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "Callback payload" } } } } } - */ - callbacks?: Record - - /** - * Declares this operation to be deprecated. Consumers SHOULD refrain from using - * the declared operation. Default value is false. - * - * @example true - * @example false - */ - deprecated?: boolean - - /** - * A declaration of which security mechanisms can be used for this operation. - * The list of values includes alternative security requirement objects that can - * be used. Only one of the security requirement objects need to be satisfied - * to authorize a request. - * - * @example [{ "petstore_auth": ["write:pets", "read:pets"] }] - */ - security?: SecurityRequirement[] - - /** - * An alternative server array to service this operation. If an alternative - * server object is specified at the Path Item Object level, it will be - * overridden by this value. - * - * @example [{ url: "https://api.example.com/v1" }] - */ - servers?: Server[] -} - -/** - * ----- - * Example Object - * ----- - * - * In all cases, the example value is expected to be compatible with the type schema - * of its associated value. Tooling implementations MAY choose to validate compatibility - * automatically, and reject the example value(s) if incompatible. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#example-object | OpenAPI 3.1.1 Example Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#example-object | OpenAPI 3.1.0 Example Object} | - * - * ----- - * Fields - * ----- - * - * @key `summary` - Optional Short description for the example - * @key `description` - Optional Long description for the example - * @key `value` - Optional Embedded literal example - * @key `externalValue` - Optional A URI that points to the literal example - * @key `x-${string}` - Specification Extensions - * - * @note - * The `value` and `externalValue` fields are mutually exclusive. - * - * ----- - * Examples - * ----- - * - * @example (embedded example): - * ```ts - * const example: Example = { - * summary: "A user example", - * value: { - * id: 1, - * name: "John Doe", - * email: "john@example.com" - * } - * }; - * ``` - * - * @example (external example): - * ```ts - * const example: Example = { - * summary: "External user example", - * externalValue: "https://example.com/examples/user-example.json" - * }; - * ``` - */ -export interface Example extends Extension { - /** - * Short description for the example. - * - * @example "A user example" - * @example "Error response example" - */ - summary?: string - - /** - * Long description for the example. CommonMark syntax MAY be used for rich text representation. - * - * @example "This example shows a typical user object with all required fields" - * @example "This example demonstrates an error response when validation fails" - */ - description?: string - - /** - * Embedded literal example. The value field and externalValue field are mutually exclusive. - * To represent examples of media types that cannot naturally represented in JSON or YAML, - * use a string value to contain the example, escaping where necessary. - * - * @example { id: 1, name: "John Doe" } - * @example "example string" - * @example 42 - */ - value?: unknown - - /** - * A URI that points to the literal example. This provides the capability to reference - * examples that cannot easily be included in JSON or YAML documents. The value field - * and externalValue field are mutually exclusive. - * - * @example "https://example.com/examples/user-example.json" - * @example "https://example.com/examples/error-example.xml" - */ - externalValue?: string -} - -/** - * ----- - * Parameter Object - * ----- - * - * Describes a single operation parameter. A unique parameter is defined by a combination - * of a name and location. The parameter name is case sensitive. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#parameter-object | OpenAPI 3.1.1 Parameter Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#parameter-object | OpenAPI 3.1.0 Parameter Object} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Required The name of the parameter - * @key `in` - Required The location of the parameter - * @key `description` - Optional A brief description of the parameter - * @key `required` - Optional Determines whether this parameter is mandatory - * @key `deprecated` - Optional Specifies that a parameter is deprecated - * @key `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters - * @key `style` - Optional Describes how the parameter value will be serialized - * @key `explode` - Optional When this is true, parameter values of type array or object generate separate parameters for each value - * @key `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters - * @key `schema` - Optional The schema defining the type used for the parameter - * @key `example` - Optional Example of the parameter's potential value - * @key `examples` - Optional Examples of the parameter's potential value - * @key `content` - Optional A map containing the representations for the parameter - * @key `x-${string}` - Specification Extensions - * - * @note - * The `schema` and `content` fields are mutually exclusive. For path parameters, `required` must be true. - * - * ----- - * Examples - * ----- - * - * @example (query parameter): - * ```ts - * const parameter: Parameter = { - * name: "limit", - * in: "query", - * description: "Maximum number of items to return", - * required: false, - * schema: { type: "integer", minimum: 1, maximum: 100 } - * }; - * ``` - * - * @example (path parameter): - * ```ts - * const parameter: Parameter = { - * name: "userId", - * in: "path", - * description: "The user ID", - * required: true, - * schema: { type: "string" } - * }; - * ``` - */ -export interface Parameter extends Extension { - /** - * The name of the parameter. Parameter names are case sensitive. - * - * @example "userId" - * @example "limit" - * @example "X-API-Key" - */ - name: string - - /** - * The location of the parameter. Possible values are "query", "header", "path" or "cookie". - * - * @example "query" - * @example "path" - * @example "header" - * @example "cookie" - */ - in: "query" | "header" | "path" | "cookie" - - /** - * A brief description of the parameter. This could contain examples of use. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "The user ID to retrieve" - * @example "Maximum number of items to return" - */ - description?: string - - /** - * Determines whether this parameter is mandatory. If the parameter location is "path", - * this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be - * included and its default value is false. - * - * @example true - * @example false - */ - required?: boolean - - /** - * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. - * Default value is false. - * - * @example true - * @example false - */ - deprecated?: boolean - - /** - * Sets the ability to pass empty-valued parameters. This is valid only for query - * parameters and allows sending a parameter with an empty value. Default value is false. - * - * @example true - * @example false - */ - allowEmptyValue?: boolean - - /** - * Describes how the parameter value will be serialized depending on the type of the - * parameter value. Default values (based on value of in): for query - form; for path - simple; - * for header - simple; for cookie - form. - * - * @example "simple" - * @example "form" - * @example "matrix" - * @example "label" - * @example "spaceDelimited" - * @example "pipeDelimited" - * @example "deepObject" - */ - style?: string - - /** - * When this is true, parameter values of type array or object generate separate parameters - * for each value of the array or key-value pair of the map. For other types of parameters - * this property has no effect. When style is form, the default value is true. For all other - * styles, the default value is false. - * - * @example true - * @example false - */ - explode?: boolean - - /** - * Determines whether the parameter value SHOULD allow reserved characters, as defined by - * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only - * applies to parameters with an in value of query. The default value is false. - * - * @example true - * @example false - */ - allowReserved?: boolean - - /** - * The schema defining the type used for the parameter. This field is mutually exclusive - * with the content field. - * - * @example { type: "string" } - * @example { type: "integer", minimum: 1 } - */ - schema?: Schema - - /** - * Example of the parameter's potential value. The example SHOULD match the specified - * schema and encoding properties if present. The example field is mutually exclusive - * of the examples field. Furthermore, if referencing a schema that contains an example, - * the example value SHALL override the example provided by the schema. - * - * @example "example value" - * @example 42 - * @example { id: 1, name: "John" } - */ - example?: unknown - - /** - * Examples of the parameter's potential value. Each example SHOULD contain a value in - * the correct format as specified in the parameter encoding. The examples field is - * mutually exclusive of the example field. Furthermore, if referencing a schema that - * contains an example, the examples value SHALL override the example provided by the schema. - * - * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } } - */ - examples?: Record - - /** - * A map containing the representations for the parameter. The key is the media type - * and the value describes it. The map MUST only contain one entry. This field is - * mutually exclusive with the schema field. - * - * @example { "application/json": { schema: { type: "string" } } } - */ - content?: Record -} - -/** - * ----- - * Request Body Object - * ----- - * - * Describes a single request body. A request body is the payload sent with an HTTP request. - * The request body is only supported in HTTP methods where the HTTP 1.1 specification - * RFC7231 has explicitly defined semantics for request bodies. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#request-body-object | OpenAPI 3.1.1 Request Body Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#request-body-object | OpenAPI 3.1.0 Request Body Object} | - * - * ----- - * Fields - * ----- - * - * @key `description` - Optional A brief description of the request body - * @key `content` - Required The content of the request body - * @key `required` - Optional Determines if the request body is required in the request - * @key `x-${string}` - Specification Extensions - * - * @note - * The `content` field is required and must contain at least one media type. - * - * ----- - * Examples - * ----- - * - * @example (JSON request body): - * ```ts - * const requestBody: RequestBody = { - * description: "User data to create", - * required: true, - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/User" } - * } - * } - * }; - * ``` - * - * @example (multipart request body): - * ```ts - * const requestBody: RequestBody = { - * description: "File upload", - * content: { - * "multipart/form-data": { - * schema: { - * type: "object", - * properties: { - * file: { type: "string", format: "binary" } - * } - * } - * } - * } - * }; - * ``` - */ -export interface RequestBody extends Extension { - /** - * A brief description of the request body. This could contain examples of use. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "User data to create" - * @example "File upload with metadata" - */ - description?: string - - /** - * The content of the request body. The key is a media type or media type range and - * the value describes it. For request bodies that are sent using multipart/form-data, - * the encoding property is used to describe the encoding of the request body. - * - * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } - * @example { "multipart/form-data": { schema: { type: "object", properties: { file: { type: "string", format: "binary" } } } } } - */ - content: Record - - /** - * Determines if the request body is required in the request. Defaults to false. - * - * @example true - * @example false - */ - required?: boolean -} - -/** - * ----- - * Responses Object - * ----- - * - * A container for the expected responses of an operation. The container maps a HTTP response - * code to the expected response. The Responses Object MUST contain at least one response code, - * and it SHOULD be the response for a successful operation call. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#responses-object | OpenAPI 3.1.1 Responses Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#responses-object | OpenAPI 3.1.0 Responses Object} | - * - * ----- - * Fields - * ----- - * - * @key `{statusCode}` - A HTTP status code or range of status codes - * @key `default` - The documentation of responses other than the ones declared for specific HTTP response codes - * - * @note - * The Responses Object MUST contain at least one response code. The `default` key can be used - * to define a default response for all HTTP codes that are not covered individually by the specification. - * - * ----- - * Examples - * ----- - * - * @example (basic responses): - * ```ts - * const responses: Responses = { - * "200": { - * description: "A list of users", - * content: { - * "application/json": { - * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } - * } - * } - * }, - * "default": { - * description: "Unexpected error" - * } - * }; - * ``` - * - * @example (with multiple status codes): - * ```ts - * const responses: Responses = { - * "200": { description: "Success", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } }, - * "400": { description: "Bad Request" }, - * "404": { description: "Not Found" }, - * "500": { description: "Internal Server Error" } - * }; - * ``` - */ -export interface Responses { - /** - * A HTTP status code or range of status codes. The key can be a specific status code - * (e.g., "200", "404") or a range (e.g., "2XX", "4XX"). The value describes the response - * for that status code. - * - * @example "200" - * @example "404" - * @example "2XX" - * @example "4XX" - * @example "default" - */ - [statusCode: string]: Response | Reference -} - -/** - * ----- - * Response Object - * ----- - * - * Describes a single response from an API Operation, including design-time, static links - * to operations based on the response. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#response-object | OpenAPI 3.1.1 Response Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#response-object | OpenAPI 3.1.0 Response Object} | - * - * ----- - * Fields - * ----- - * - * @key `description` - Required A short description of the response - * @key `headers` - Optional Maps a header name to its definition - * @key `content` - Optional A map containing descriptions of potential response payloads - * @key `links` - Optional A map of operations links that can be followed from the response - * @key `x-${string}` - Specification Extensions - * - * @note - * The `description` field is required and should describe the response. - * - * ----- - * Examples - * ----- - * - * @example (basic response): - * ```ts - * const response: Response = { - * description: "A list of users", - * content: { - * "application/json": { - * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } - * } - * } - * }; - * ``` - * - * @example (response with headers): - * ```ts - * const response: Response = { - * description: "User created successfully", - * headers: { - * "Location": { - * description: "URL of the created user", - * schema: { type: "string" } - * } - * }, - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/User" } - * } - * } - * }; - * ``` - */ -export interface Response extends Extension { - /** - * A short description of the response. CommonMark syntax MAY be used for rich text representation. - * This field is required. - * - * @example "A list of users" - * @example "User created successfully" - * @example "Bad request - validation failed" - */ - description: string - - /** - * Maps a header name to its definition. RFC7230 states header names are case insensitive. - * If a response header is defined with the name "Content-Type", it SHALL be ignored. - * - * @example { "X-RateLimit-Limit": { description: "Rate limit per hour", schema: { type: "integer" } } } - */ - headers?: Record - - /** - * A map containing descriptions of potential response payloads. The key is a media type - * or media type range and the value describes it. For responses that match multiple keys, - * only the most specific key is applicable. e.g. text/plain overrides text/* - * - * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } - * @example { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/User" } } } } - */ - content?: Record - - /** - * A map of operations links that can be followed from the response. The key of the map - * is a short name for the link, following the naming constraints of the names for - * Component Objects. - * - * @example { "GetUser": { operationId: "getUserById", parameters: { userId: "$response.body#/id" } } } - */ - links?: Record -} - -/** - * ----- - * Header Object - * ----- - * - * The Header Object follows the structure of the Parameter Object with the following changes: - * 1. `name` MUST NOT be specified, it is given in the corresponding headers map. - * 2. `in` MUST NOT be specified, it is implicitly in header. - * 3. All traits that are affected by the location MUST be applicable to a location of header - * (for example, style). - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#header-object | OpenAPI 3.1.1 Header Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#header-object | OpenAPI 3.1.0 Header Object} | - * - * ----- - * Fields - * ----- - * - * @key `description` - Optional A brief description of the header - * @key `required` - Optional Determines whether this header is mandatory - * @key `deprecated` - Optional Specifies that a header is deprecated - * @key `allowEmptyValue` - Optional Sets the ability to pass empty-valued headers - * @key `style` - Optional Describes how the header value will be serialized - * @key `explode` - Optional When this is true, header values of type array or object generate separate headers for each value - * @key `allowReserved` - Optional Determines whether the header value SHOULD allow reserved characters - * @key `schema` - Optional The schema defining the type used for the header - * @key `example` - Optional Example of the header's potential value - * @key `examples` - Optional Examples of the header's potential value - * @key `content` - Optional A map containing the representations for the header - * @key `x-${string}` - Specification Extensions - * - * @note - * The `schema` and `content` fields are mutually exclusive. - * - * ----- - * Examples - * ----- - * - * @example (simple header): - * ```ts - * const header: Header = { - * description: "Rate limit per hour", - * required: false, - * schema: { type: "integer" } - * }; - * ``` - * - * @example (header with content): - * ```ts - * const header: Header = { - * description: "Custom header with JSON content", - * content: { - * "application/json": { - * schema: { type: "object", properties: { value: { type: "string" } } } - * } - * } - * }; - * ``` - */ -export interface Header extends Extension { - /** - * A brief description of the header. This could contain examples of use. - * CommonMark syntax MAY be used for rich text representation. - * - * @example "Rate limit per hour" - * @example "Custom authentication token" - */ - description?: string - - /** - * Determines whether this header is mandatory. The property MAY be included and its - * default value is false. - * - * @example true - * @example false - */ - required?: boolean - - /** - * Specifies that a header is deprecated and SHOULD be transitioned out of usage. - * Default value is false. - * - * @example true - * @example false - */ - deprecated?: boolean - - /** - * Sets the ability to pass empty-valued headers. This is valid only for headers - * and allows sending a header with an empty value. Default value is false. - * - * @example true - * @example false - */ - allowEmptyValue?: boolean - - /** - * Describes how the header value will be serialized. The default value is "simple". - * - * @example "simple" - * @example "form" - */ - style?: string - - /** - * When this is true, header values of type array or object generate separate headers - * for each value of the array or key-value pair of the map. For other types of headers - * this property has no effect. When style is form, the default value is true. For all other - * styles, the default value is false. - * - * @example true - * @example false - */ - explode?: boolean - - /** - * Determines whether the header value SHOULD allow reserved characters, as defined by - * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. - * - * @example true - * @example false - */ - allowReserved?: boolean - - /** - * The schema defining the type used for the header. This field is mutually exclusive - * with the content field. - * - * @example { type: "string" } - * @example { type: "integer", minimum: 0 } - */ - schema?: Schema - - /** - * Example of the header's potential value. The example SHOULD match the specified - * schema and encoding properties if present. The example field is mutually exclusive - * of the examples field. - * - * @example "example value" - * @example 42 - */ - example?: unknown - - /** - * Examples of the header's potential value. Each example SHOULD contain a value in - * the correct format as specified in the header encoding. The examples field is - * mutually exclusive of the example field. - * - * @example { "header1": { summary: "A header example", value: "example value" } } - */ - examples?: Record - - /** - * A map containing the representations for the header. The key is the media type - * and the value describes it. The map MUST only contain one entry. This field is - * mutually exclusive with the schema field. - * - * @example { "application/json": { schema: { type: "string" } } } - */ - content?: Record -} - -/** - * ----- - * Media Type Object - * ----- - * - * Each Media Type Object provides schema and examples for the media type identified by its key. - * Media Type Objects can be used in a Content Object. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#media-type-object | OpenAPI 3.1.1 Media Type Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#media-type-object | OpenAPI 3.1.0 Media Type Object} | - * - * ----- - * Fields - * ----- - * - * @key `schema` - Optional The schema defining the content of the request, response, or parameter - * @key `example` - Optional Example of the media type - * @key `examples` - Optional Examples of the media type - * @key `encoding` - Optional A map between a property name and its encoding information - * @key `x-${string}` - Specification Extensions - * - * @note - * The `example` and `examples` fields are mutually exclusive. - * - * ----- - * Examples - * ----- - * - * @example (JSON media type): - * ```ts - * const mediaType: MediaType = { - * schema: { $ref: "#/components/schemas/User" }, - * example: { id: 1, name: "John Doe" } - * }; - * ``` - * - * @example (multipart media type with encoding): - * ```ts - * const mediaType: MediaType = { - * schema: { - * type: "object", - * properties: { - * file: { type: "string", format: "binary" }, - * description: { type: "string" } - * } - * }, - * encoding: { - * file: { contentType: "image/png" }, - * description: { contentType: "text/plain" } - * } - * }; - * ``` - */ -export interface MediaType extends Extension { - /** - * The schema defining the content of the request, response, or parameter. - * - * @example { $ref: "#/components/schemas/User" } - * @example { type: "array", items: { type: "string" } } - */ - schema?: Schema - - /** - * Example of the media type. The example SHOULD match the specified schema and encoding - * properties if present. The example field is mutually exclusive of the examples field. - * Furthermore, if referencing a schema that contains an example, the example value - * SHALL override the example provided by the schema. - * - * @example { id: 1, name: "John Doe" } - * @example "example string" - * @example 42 - */ - example?: unknown - - /** - * Examples of the media type. Each example SHOULD contain a value in the correct format - * as specified in the media type encoding. The examples field is mutually exclusive - * of the example field. Furthermore, if referencing a schema that contains an example, - * the examples value SHALL override the example provided by the schema. - * - * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } } - */ - examples?: Record - - /** - * A map between a property name and its encoding information. The key, being the property - * name, MUST exist in the schema as a property. The encoding object SHALL only apply to - * requestBody objects when the media type is multipart or application/x-www-form-urlencoded. - * - * @example { "file": { contentType: "image/png" }, "description": { contentType: "text/plain" } } - */ - encoding?: Record -} - -/** - * ----- - * Encoding Object - * ----- - * - * A single encoding definition applied to a single schema property. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#encoding-object | OpenAPI 3.1.1 Encoding Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#encoding-object | OpenAPI 3.1.0 Encoding Object} | - * - * ----- - * Fields - * ----- - * - * @key `contentType` - Optional The Content-Type for encoding a specific property - * @key `headers` - Optional A map allowing additional information to be provided as headers - * @key `style` - Optional Describes how a specific property value will be serialized - * @key `explode` - Optional When this is true, property values of type array or object generate separate parameters for each value - * @key `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters - * @key `x-${string}` - Specification Extensions - * - * @note - * The `style` property only applies to form data and query parameters. - * - * ----- - * Examples - * ----- - * - * @example (basic encoding): - * ```ts - * const encoding: Encoding = { - * contentType: "image/png", - * style: "form" - * }; - * ``` - * - * @example (encoding with headers): - * ```ts - * const encoding: Encoding = { - * contentType: "application/json", - * headers: { - * "X-Custom-Header": { - * description: "Custom header for this encoding", - * schema: { type: "string" } - * } - * } - * }; - * ``` - */ -export interface Encoding extends Extension { - /** - * The Content-Type for encoding a specific property. Default value depends on the - * property type: for string with format being binary – application/octet-stream; - * for other primitive types – text/plain; for object – application/json; - * for array – the default is determined based on the inner type. - * - * @example "image/png" - * @example "application/json" - * @example "text/plain" - */ - contentType?: string - - /** - * A map allowing additional information to be provided as headers, for example - * Content-Disposition. Content-Type is described separately and SHALL be ignored - * in this section. This property SHALL be ignored if the request body media type - * is not a multipart. - * - * @example { "Content-Disposition": { description: "File attachment", schema: { type: "string" } } } - */ - headers?: Record - - /** - * Describes how a specific property value will be serialized depending on its type. - * See Parameter Object for details on the style property. The behavior follows the - * same values as query parameters, including default values. This property SHALL be - * ignored if the request body media type is not application/x-www-form-urlencoded - * or multipart/form-data. - * - * @example "form" - * @example "spaceDelimited" - * @example "pipeDelimited" - * @example "deepObject" - */ - style?: string - - /** - * When this is true, property values of type array or object generate separate - * parameters for each value of the array or key-value pair of the map. For other - * types of properties this property has no effect. When style is form, the default - * value is true. For all other styles, the default value is false. This property - * SHALL be ignored if the request body media type is not application/x-www-form-urlencoded - * or multipart/form-data. - * - * @example true - * @example false - */ - explode?: boolean - - /** - * Determines whether the parameter value SHOULD allow reserved characters, as defined - * by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default - * value is false. This property SHALL be ignored if the request body media type is - * not application/x-www-form-urlencoded. - * - * @example true - * @example false - */ - allowReserved?: boolean -} - -/** - * ----- - * Link Object - * ----- - * - * The Link object represents a possible design-time link for a response. The presence of a link - * does not guarantee the caller's ability to successfully invoke it, rather it provides a known - * relationship and traversal mechanism between responses and other operations. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#link-object | OpenAPI 3.1.1 Link Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#link-object | OpenAPI 3.1.0 Link Object} | - * - * ----- - * Fields - * ----- - * - * @key `operationRef` - Optional A relative or absolute reference to an OAS operation - * @key `operationId` - Optional The name of an existing, resolvable OAS operation - * @key `parameters` - Optional A map representing parameters to pass to an operation - * @key `requestBody` - Optional A literal value or expression to use as a request body - * @key `description` - Optional A description of the link - * @key `server` - Optional A server object to be used by the target operation - * @key `x-${string}` - Specification Extensions - * - * @note - * The `operationRef` and `operationId` fields are mutually exclusive. - * - * ----- - * Examples - * ----- - * - * @example (link with operationId): - * ```ts - * const link: Link = { - * operationId: "getUserById", - * parameters: { - * userId: "$response.body#/id" - * }, - * description: "Get the user by ID" - * }; - * ``` - * - * @example (link with operationRef): - * ```ts - * const link: Link = { - * operationRef: "#/paths/~1users~1{userId}/get", - * parameters: { - * userId: "$response.body#/id" - * } - * }; - * ``` - */ -export interface Link extends Extension { - /** - * A relative or absolute reference to an OAS operation. This field is mutually exclusive - * of the operationId field, and MUST point to an Operation Object. Relative operationRef - * values MAY be used to locate an existing Operation Object in the OpenAPI definition. - * - * @example "#/paths/~1users~1{userId}/get" - * @example "https://example.com/openapi.json#/paths/~1users~1{userId}/get" - */ - operationRef?: string - - /** - * The name of an existing, resolvable OAS operation, as defined with a unique operationId. - * This field is mutually exclusive of the operationRef field. - * - * @example "getUserById" - * @example "createUser" - */ - operationId?: string - - /** - * A map representing parameters to pass to an operation as specified with operationId - * or identified via operationRef. The key is the parameter name to be used, whereas - * the value can be a constant or an expression to be evaluated and passed to the linked - * operation. The parameter name can be qualified using the parameter location [{in}.]{name} - * for operations that use the same parameter name in different locations (e.g. path.id). - * - * @example { "userId": "$response.body#/id" } - * @example { "path.id": "$response.body#/id", "query.limit": 10 } - */ - parameters?: Record - - /** - * A literal value or expression to use as a request body when calling the target operation. - * - * @example { "name": "John Doe", "email": "john@example.com" } - * @example "$request.body" - */ - requestBody?: unknown - - /** - * A description of the link. CommonMark syntax MAY be used for rich text representation. - * - * @example "Get the user by ID" - * @example "Create a new user with the provided data" - */ - description?: string - - /** - * A server object to be used by the target operation. - * - * @example { url: "https://api.example.com/v1" } - */ - server?: Server -} - -/** - * ----- - * Callback Object - * ----- - * - * A map of possible out-of band callbacks related to the parent operation. Each value in the map - * is a Path Item Object that describes a set of requests that may be initiated by the API provider - * and the expected responses. The key value used to identify the callback object is an expression, - * evaluated at runtime, that identifies a URL to use for the callback operation. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#callback-object | OpenAPI 3.1.1 Callback Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#callback-object | OpenAPI 3.1.0 Callback Object} | - * - * ----- - * Fields - * ----- - * - * @key `{expression}` - A Path Item Object or Reference to a Path Item Object - * - * @note - * The key is a runtime expression that identifies a URL to use for the callback operation. - * The expression is evaluated at runtime and MUST resolve to a URL. - * - * ----- - * Examples - * ----- - * - * @example (simple callback): - * ```ts - * const callback: Callback = { - * "{$request.body#/callbackUrl}": { - * post: { - * requestBody: { - * description: "Callback payload", - * content: { - * "application/json": { - * schema: { $ref: "#/components/schemas/CallbackPayload" } - * } - * } - * }, - * responses: { - * "200": { - * description: "Callback received successfully" - * } - * } - * } - * } - * }; - * ``` - * - * @example (callback with multiple operations): - * ```ts - * const callback: Callback = { - * "{$request.body#/callbackUrl}": { - * post: { - * summary: "Success callback", - * requestBody: { description: "Success payload" } - * }, - * put: { - * summary: "Update callback", - * requestBody: { description: "Update payload" } - * } - * } - * }; - * ``` - */ -export interface Callback { - /** - * A runtime expression that identifies a URL to use for the callback operation. - * The expression is evaluated at runtime and MUST resolve to a URL. The value - * is a Path Item Object that describes the callback operations. - * - * @example "{$request.body#/callbackUrl}" - * @example "{$request.body#/webhookUrl}" - * @example "{$request.body#/notificationUrl}" - */ - [expression: string]: PathItemObject | Reference -} diff --git a/3.1.x/schema.ts b/3.1.x/schema.ts deleted file mode 100644 index 61e165b..0000000 --- a/3.1.x/schema.ts +++ /dev/null @@ -1,255 +0,0 @@ -import type { Extension } from "./extensions" -import type { Reference } from "./references" -import type { XML } from "./xml" -import type { ExternalDocumentation } from "./externalDocs" -import type { - ReferenceSchema, - StringSchema, - NumberSchema, - IntegerSchema, - BooleanSchema, - ArraySchema, - ObjectSchema, - CompositionSchema, -} from "./data-types" - -/** - * ----- - * Discriminator Object - * ----- - * - * The Discriminator Object is used to aid in serialization, deserialization, and validation. - * It can be used to differentiate between other schemas which may satisfy the payload description. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#discriminator-object | OpenAPI 3.1.1 Discriminator Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#discriminator-object | OpenAPI 3.1.0 Discriminator Object} | - * - * ----- - * Fields - * ----- - * - * @key `propertyName` - Required The name of the property in the payload that will hold the discriminator value - * @key `mapping` - Optional An object to hold mappings between payload values and schema names or references - * @key `x-${string}` - Specification Extensions - * - * @note - * The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. - * - * ----- - * Examples - * ----- - * - * @example (basic discriminator): - * ```ts - * const discriminator: Discriminator = { - * propertyName: "petType" - * }; - * ``` - * - * @example (discriminator with mapping): - * ```ts - * const discriminator: Discriminator = { - * propertyName: "petType", - * mapping: { - * dog: "#/components/schemas/Dog", - * cat: "#/components/schemas/Cat" - * } - * }; - * ``` - */ -export interface Discriminator extends Extension { - /** - * The name of the property in the payload that will hold the discriminator value. - * This property must be present in the payload. - * - * Example: `"petType"` - */ - propertyName: string - - /** - * An object to hold mappings between payload values and schema names or references. - * If not provided, the schema name will be used as the discriminator value. - * - * Example: `{ dog: "#/components/schemas/Dog", cat: "#/components/schemas/Cat" }` - */ - mapping?: Record -} - -/** - * ----- - * Schema Object - * ----- - * - * The Schema Object allows the definition of input and output data types. These types - * can be objects, but also primitives and arrays. This object is an extended subset - * of the JSON Schema Specification Draft 2020-12. - * - * The Schema Object is a discriminated union that enforces mutual-exclusion and - * co-occurrence rules as specified in the OpenAPI 3.1.x specification. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} | - * - * ----- - * Schema Types - * ----- - * - * The Schema union includes the following types: - * - * **Reference Schema:** - * @key `$ref` - A reference to a schema (exclusive with other properties) - * @key `description` - A description of the referenced schema - * - * **String Schema:** - * @key `type: "string"` - The type identifier for string schemas - * @key `format` - The format of the string (email, date, uuid, etc.) - * @key `maxLength` - The maximum length of the string - * @key `minLength` - The minimum length of the string - * @key `pattern` - A regular expression pattern the string must match - * @key `enum` - An enumeration of string values - * @key `const` - A constant string value - * - * **Number Schema:** - * @key `type: "number"` - The type identifier for number schemas - * @key `format` - The format of the number (float, double) - * @key `multipleOf` - A number that must be a multiple of this value - * @key `maximum` - The maximum value (inclusive) - * @key `exclusiveMaximum` - The maximum value (exclusive) - * @key `minimum` - The minimum value (inclusive) - * @key `exclusiveMinimum` - The minimum value (exclusive) - * @key `enum` - An enumeration of number values - * @key `const` - A constant number value - * - * **Integer Schema:** - * @key `type: "integer"` - The type identifier for integer schemas - * @key `format` - The format of the integer (int32, int64) - * @key `multipleOf` - An integer that must be a multiple of this value - * @key `maximum` - The maximum value (inclusive) - * @key `exclusiveMaximum` - The maximum value (exclusive) - * @key `minimum` - The minimum value (inclusive) - * @key `exclusiveMinimum` - The minimum value (exclusive) - * @key `enum` - An enumeration of integer values - * @key `const` - A constant integer value - * - * **Boolean Schema:** - * @key `type: "boolean"` - The type identifier for boolean schemas - * @key `enum` - An enumeration of boolean values - * @key `const` - A constant boolean value - * - * **Array Schema:** - * @key `type: "array"` - The type identifier for array schemas - * @key `items` - The schema for array items - * @key `prefixItems` - The schema for array items at specific positions - * @key `contains` - The schema that array must contain at least one item matching - * @key `minContains` - The minimum number of items that must match contains - * @key `maxContains` - The maximum number of items that must match contains - * @key `minItems` - The minimum number of items in the array - * @key `maxItems` - The maximum number of items in the array - * @key `uniqueItems` - Whether array items must be unique - * - * **Object Schema:** - * @key `type: "object"` - The type identifier for object schemas - * @key `properties` - A map of property names to their schemas - * @key `required` - An array of required property names - * @key `additionalProperties` - The schema for additional properties - * @key `patternProperties` - A map of regex patterns to schemas - * @key `propertyNames` - The schema for property names - * @key `minProperties` - The minimum number of properties - * @key `maxProperties` - The maximum number of properties - * @key `dependentRequired` - A map of property names to arrays of required properties - * @key `dependentSchemas` - A map of property names to schemas - * - * **Composition Schema:** - * @key `allOf` - An array of schemas that must all be satisfied - * @key `anyOf` - An array of schemas where at least one must be satisfied - * @key `oneOf` - An array of schemas where exactly one must be satisfied - * @key `not` - A schema that must not be satisfied - * @key `if` - A schema for conditional validation - * @key `then` - A schema to apply if if condition is met - * @key `else` - A schema to apply if if condition is not met - * - * **Common Properties:** - * @key `title` - A short title for the schema - * @key `description` - A description of the schema - * @key `default` - The default value for the schema - * @key `examples` - An array of example values - * @key `enum` - An enumeration of allowed values - * @key `const` - A constant allowed value - * @key `discriminator` - A discriminator object for polymorphism - * @key `xml` - XML-specific metadata - * @key `externalDocs` - External documentation - * @key `x-${string}` - Specification Extensions - * - * @note - * The Schema Object is a discriminated union that enforces mutual-exclusion and - * co-occurrence rules. When `$ref` is present, no other properties except - * `description` and extensions are allowed. Composition keywords are mutually - * exclusive with `$ref`. - * - * ----- - * Examples - * ----- - * - * @example (reference schema): - * ```ts - * const schema: Schema = { - * $ref: "#/components/schemas/User" - * }; - * ``` - * - * @example (string schema): - * ```ts - * const schema: Schema = { - * type: "string", - * format: "email", - * maxLength: 255 - * }; - * ``` - * - * @example (object schema): - * ```ts - * const schema: Schema = { - * type: "object", - * properties: { - * name: { type: "string" }, - * age: { type: "number" } - * }, - * required: ["name"] - * }; - * ``` - * - * @example (composition schema): - * ```ts - * const schema: Schema = { - * allOf: [ - * { type: "object", properties: { name: { type: "string" } } }, - * { type: "object", properties: { age: { type: "number" } } } - * ] - * }; - * ``` - */ -export type Schema = - | ReferenceSchema - | StringSchema - | NumberSchema - | IntegerSchema - | BooleanSchema - | ArraySchema - | ObjectSchema - | CompositionSchema - -// Re-export individual schema types for convenience -export type { - ReferenceSchema, - StringSchema, - NumberSchema, - IntegerSchema, - BooleanSchema, - ArraySchema, - ObjectSchema, - CompositionSchema, -} from "./data-types" diff --git a/3.1.x/security.ts b/3.1.x/security.ts deleted file mode 100644 index e64671d..0000000 --- a/3.1.x/security.ts +++ /dev/null @@ -1,358 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * Security Scheme Object - * ----- - * - * Defines a security scheme that can be used by the operations. Supported schemes - * are HTTP authentication, an API key (either as a header, a cookie parameter or - * as a query parameter), mutual TLS (use of a client certificate), OAuth2's common - * flows (implicit, password, client credentials and authorization code) as defined - * in RFC6749, and OpenID Connect Discovery. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#security-scheme-object | OpenAPI 3.1.1 Security Scheme Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#security-scheme-object | OpenAPI 3.1.0 Security Scheme Object} | - * - * ----- - * Fields - * ----- - * - * @key `type` - Required The type of the security scheme - * @key `description` - Optional A short description for security scheme - * @key `name` - Optional The name of the header, query or cookie parameter to be used - * @key `in` - Optional The location of the API key - * @key `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header - * @key `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted - * @key `flows` - Optional An object containing configuration information for the flow types supported - * @key `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values - * @key `x-${string}` - Specification Extensions - * - * @note - * The `type` field is required. Other fields depend on the security scheme type. - * - * ----- - * Examples - * ----- - * - * @example (API Key): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "apiKey", - * name: "X-API-Key", - * in: "header" - * }; - * ``` - * - * @example (HTTP Basic): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "http", - * scheme: "basic" - * }; - * ``` - * - * @example (OAuth2): - * ```ts - * const securityScheme: SecurityScheme = { - * type: "oauth2", - * flows: { - * authorizationCode: { - * authorizationUrl: "https://example.com/oauth/authorize", - * tokenUrl: "https://example.com/oauth/token", - * scopes: { - * "read:pets": "read your pets", - * "write:pets": "modify pets in your account" - * } - * } - * } - * }; - * ``` - */ -export interface SecurityScheme extends Extension { - /** - * The type of the security scheme. This field is required. - * - * @example "apiKey" - * @example "http" - * @example "oauth2" - * @example "openIdConnect" - */ - type: "apiKey" | "http" | "oauth2" | "openIdConnect" - - /** - * A short description for security scheme. CommonMark syntax MAY be used - * for rich text representation. - * - * @example "API key authentication" - * @example "OAuth2 authentication with authorization code flow" - */ - description?: string - - /** - * The name of the header, query or cookie parameter to be used. This field - * is required for `apiKey` type. - * - * @example "X-API-Key" - * @example "api_key" - * @example "sessionId" - */ - name?: string - - /** - * The location of the API key. This field is required for `apiKey` type. - * - * @example "header" - * @example "query" - * @example "cookie" - */ - in?: "query" | "header" | "cookie" - - /** - * The name of the HTTP Authorization scheme to be used in the Authorization - * header. This field is required for `http` type. - * - * @example "basic" - * @example "bearer" - * @example "digest" - */ - scheme?: string - - /** - * A hint to the client to identify how the bearer token is formatted. Bearer - * tokens are usually generated by an authorization server, so this information - * is primarily for documentation purposes. - * - * @example "JWT" - * @example "Bearer" - */ - bearerFormat?: string - - /** - * An object containing configuration information for the flow types supported. - * This field is required for `oauth2` type. - * - * @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } } - */ - flows?: OAuthFlows - - /** - * OpenId Connect URL to discover OAuth2 configuration values. This MUST be - * in the form of a URL. This field is required for `openIdConnect` type. - * - * @example "https://example.com/.well-known/openid_configuration" - */ - openIdConnectUrl?: string -} - -/** - * ----- - * OAuth Flows Object - * ----- - * - * Allows configuration of the supported OAuth Flows. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flows-object | OpenAPI 3.1.1 OAuth Flows Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flows-object | OpenAPI 3.1.0 OAuth Flows Object} | - * - * ----- - * Fields - * ----- - * - * @key `implicit` - Optional Configuration for the OAuth Implicit flow - * @key `password` - Optional Configuration for the OAuth Resource Owner Password flow - * @key `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow - * @key `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow - * @key `x-${string}` - Specification Extensions - * - * @note - * All fields are optional. At least one flow must be specified. - * - * ----- - * Examples - * ----- - * - * @example (authorization code flow): - * ```ts - * const oauthFlows: OAuthFlows = { - * authorizationCode: { - * authorizationUrl: "https://example.com/oauth/authorize", - * tokenUrl: "https://example.com/oauth/token", - * scopes: { - * "read:pets": "read your pets", - * "write:pets": "modify pets in your account" - * } - * } - * }; - * ``` - */ -export interface OAuthFlows extends Extension { - /** - * Configuration for the OAuth Implicit flow. - * - * @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { "read:pets": "read your pets" } } - */ - implicit?: OAuthFlow - - /** - * Configuration for the OAuth Resource Owner Password flow. - * - * @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } } - */ - password?: OAuthFlow - - /** - * Configuration for the OAuth Client Credentials flow. - * - * @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } } - */ - clientCredentials?: OAuthFlow - - /** - * Configuration for the OAuth Authorization Code flow. - * - * @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } } - */ - authorizationCode?: OAuthFlow -} - -/** - * ----- - * OAuth Flow Object - * ----- - * - * Configuration details for a supported OAuth Flow. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flow-object | OpenAPI 3.1.1 OAuth Flow Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flow-object | OpenAPI 3.1.0 OAuth Flow Object} | - * - * ----- - * Fields - * ----- - * - * @key `authorizationUrl` - Optional The authorization URL to be used for this flow - * @key `tokenUrl` - Optional The token URL to be used for this flow - * @key `refreshUrl` - Optional The URL to be used for obtaining refresh tokens - * @key `scopes` - Required The available scopes for the OAuth2 security scheme - * @key `x-${string}` - Specification Extensions - * - * @note - * The `scopes` field is required. Other fields depend on the flow type. - * - * ----- - * Examples - * ----- - * - * @example (authorization code flow): - * ```ts - * const oauthFlow: OAuthFlow = { - * authorizationUrl: "https://example.com/oauth/authorize", - * tokenUrl: "https://example.com/oauth/token", - * scopes: { - * "read:pets": "read your pets", - * "write:pets": "modify pets in your account" - * } - * }; - * ``` - */ -export interface OAuthFlow extends Extension { - /** - * The authorization URL to be used for this flow. This MUST be in the form of a URL. - * This field is required for `implicit` and `authorizationCode` flows. - * - * @example "https://example.com/oauth/authorize" - */ - authorizationUrl?: string - - /** - * The token URL to be used for this flow. This MUST be in the form of a URL. - * This field is required for `password`, `clientCredentials`, and `authorizationCode` flows. - * - * @example "https://example.com/oauth/token" - */ - tokenUrl?: string - - /** - * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. - * - * @example "https://example.com/oauth/refresh" - */ - refreshUrl?: string - - /** - * The available scopes for the OAuth2 security scheme. A map between the scope - * name and a short description for it. This field is required. - * - * @example { "read:pets": "read your pets", "write:pets": "modify pets in your account" } - */ - scopes: Record -} - -/** - * ----- - * Security Requirement Object - * ----- - * - * Lists the required security schemes for execution of the operation. The name - * used for each property MUST correspond to a security scheme declared in the - * Security Schemes under the Components Object. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#security-requirement-object | OpenAPI 3.1.1 Security Requirement Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#security-requirement-object | OpenAPI 3.1.0 Security Requirement Object} | - * - * ----- - * Fields - * ----- - * - * @key `{name}` - Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object - * - * @note - * The property names correspond to security scheme names. The values are arrays of scope names. - * - * ----- - * Examples - * ----- - * - * @example (API key): - * ```ts - * const securityRequirement: SecurityRequirement = { - * "api_key": [] - * }; - * ``` - * - * @example (OAuth2): - * ```ts - * const securityRequirement: SecurityRequirement = { - * "petstore_auth": ["write:pets", "read:pets"] - * }; - * ``` - * - * @example (multiple schemes): - * ```ts - * const securityRequirement: SecurityRequirement = { - * "api_key": [], - * "petstore_auth": ["write:pets", "read:pets"] - * }; - * ``` - */ -export interface SecurityRequirement { - /** - * Each name MUST correspond to a security scheme which is declared in the - * Security Schemes under the Components Object. The value is an array of - * scope names required for the execution. For OAuth2, the scopes are the - * scopes required for the execution. For other security schemes, the array - * MUST be empty. - * - * @example [] - * @example ["write:pets", "read:pets"] - */ - [name: string]: string[] -} diff --git a/3.1.x/servers.ts b/3.1.x/servers.ts deleted file mode 100644 index 2bcc0c8..0000000 --- a/3.1.x/servers.ts +++ /dev/null @@ -1,164 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * Server Object - * ----- - * - * An object representing a Server. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#server-object | OpenAPI 3.1.1 Server Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#server-object | OpenAPI 3.1.0 Server Object} | - * - * ----- - * Fields - * ----- - * - * @key `url` - Required A URL to the target host - * @key `description` - Optional An optional string describing the host designated by the URL - * @key `variables` - Optional A map between a variable name and its value - * @key `x-${string}` - Specification Extensions - * - * @note - * The `url` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple server): - * ```ts - * const server: Server = { - * url: "https://api.example.com/v1" - * }; - * ``` - * - * @example (server with variables): - * ```ts - * const server: Server = { - * url: "https://{username}.gigantic-server.com:{port}/{basePath}", - * description: "The production API server", - * variables: { - * username: { - * default: "demo", - * description: "this value is assigned by the service provider" - * }, - * port: { - * enum: ["8443", "443"], - * default: "8443" - * }, - * basePath: { - * default: "v2" - * } - * } - * }; - * ``` - */ -export interface Server extends Extension { - /** - * A URL to the target host. This URL supports Server Variables and MAY be relative, - * to indicate that the host location is relative to the location where the OpenAPI - * document is being served. Variable substitutions will be made when a variable - * is named in `{brackets}`. - * - * @example "https://api.example.com/v1" - * @example "https://{username}.gigantic-server.com:{port}/{basePath}" - * @example "/v1" - */ - url: string - - /** - * An optional string describing the host designated by the URL. CommonMark syntax - * MAY be used for rich text representation. - * - * @example "The production API server" - * @example "The staging API server" - */ - description?: string - - /** - * A map between a variable name and its value. The value is used for substitution - * in the server's URL template. - * - * @example { username: { default: "demo" }, port: { default: "8443" } } - */ - variables?: Record -} - -/** - * ----- - * Server Variable Object - * ----- - * - * An object representing a Server Variable for server URL template substitution. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#server-variable-object | OpenAPI 3.1.1 Server Variable Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#server-variable-object | OpenAPI 3.1.0 Server Variable Object} | - * - * ----- - * Fields - * ----- - * - * @key `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set - * @key `default` - Required The default value to use for substitution - * @key `description` - Optional An optional description for the server variable - * @key `x-${string}` - Specification Extensions - * - * @note - * The `default` field is required. - * - * ----- - * Examples - * ----- - * - * @example (simple variable): - * ```ts - * const variable: ServerVariable = { - * default: "demo" - * }; - * ``` - * - * @example (variable with enum): - * ```ts - * const variable: ServerVariable = { - * enum: ["8443", "443"], - * default: "8443", - * description: "The port number" - * }; - * ``` - */ -export interface ServerVariable extends Extension { - /** - * An enumeration of string values to be used if the substitution options are - * from a limited set. The array SHOULD NOT be empty. - * - * @example ["8443", "443"] - * @example ["v1", "v2", "v3"] - */ - enum?: string[] - - /** - * The default value to use for substitution, which SHALL be sent if an alternate - * value is not supplied. Note this behavior is different than the Schema Object's - * treatment of default values, because in those cases parameter values are optional. - * If the enum is defined, the value SHOULD exist in the enum's values. - * - * @example "demo" - * @example "8443" - * @example "v1" - */ - default: string - - /** - * An optional description for the server variable. CommonMark syntax MAY be used - * for rich text representation. - * - * @example "this value is assigned by the service provider" - * @example "The port number" - */ - description?: string -} diff --git a/3.1.x/spec.ts b/3.1.x/spec.ts deleted file mode 100644 index 8382d03..0000000 --- a/3.1.x/spec.ts +++ /dev/null @@ -1,208 +0,0 @@ -import type { Extension } from "./extensions" -import type { Info } from "./info" -import type { Server } from "./servers" -import type { Paths } from "./paths" -import type { Components } from "./components" -import type { SecurityRequirement } from "./security" -import type { Tag } from "./tags" -import type { ExternalDocumentation } from "./externalDocs" - -/** - * ----- - * OpenAPI Specification - * ----- - * - * This is the root object of the OpenAPI document. It contains all the information - * needed to describe an API, including metadata, servers, paths, components, and more. - * - * The OpenAPI Specification (OAS) defines a standard, language-agnostic interface - * to RESTful APIs which allows both humans and computers to discover and understand - * the capabilities of the service without access to source code, documentation, or - * through network traffic inspection. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#openapi-object | OpenAPI 3.1.1 OpenAPI Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#openapi-object | OpenAPI 3.1.0 OpenAPI Object} | - * - * ----- - * Fields - * ----- - * - * @key `openapi` - Required The version number of the OpenAPI Specification - * @key `info` - Required Provides metadata about the API - * @key `jsonSchemaDialect` - Optional The default value for the $schema keyword within Schema Objects - * @key `servers` - Optional An array of Server Objects - * @key `paths` - Optional The available paths and operations for the API - * @key `webhooks` - Optional The incoming webhooks that MAY be received as part of this API - * @key `components` - Optional An element to hold various schemas for the document - * @key `security` - Optional A declaration of which security mechanisms can be used across the API - * @key `tags` - Optional A list of tags used by the document with additional metadata - * @key `externalDocs` - Optional Additional external documentation - * @key `x-${string}` - Specification Extensions - * - * @note - * The `openapi` and `info` fields are required. - * - * ----- - * Examples - * ----- - * - * @example (minimal specification): - * ```ts - * const spec: Specification = { - * openapi: "3.1.0", - * info: { - * title: "Pet Store API", - * version: "1.0.0" - * } - * }; - * ``` - * - * @example (complete specification): - * ```ts - * const spec: Specification = { - * openapi: "3.1.0", - * info: { - * title: "Pet Store API", - * summary: "A sample API that uses a petstore as an example", - * description: "This is a sample server Petstore server.", - * termsOfService: "http://example.com/terms/", - * contact: { - * name: "API Support", - * url: "http://www.example.com/support", - * email: "support@example.com" - * }, - * license: { - * name: "Apache 2.0", - * url: "https://www.apache.org/licenses/LICENSE-2.0.html" - * }, - * version: "1.0.0" - * }, - * servers: [ - * { - * url: "https://api.example.com/v1", - * description: "The production API server" - * } - * ], - * paths: { - * "/pets": { - * "get": { - * "summary": "List all pets", - * "responses": { - * "200": { - * "description": "A list of pets" - * } - * } - * } - * } - * }, - * components: { - * schemas: { - * Pet: { - * type: "object", - * properties: { - * id: { type: "integer", format: "int64" }, - * name: { type: "string" } - * } - * } - * } - * }, - * tags: [ - * { - * name: "pets", - * description: "Pet store operations" - * } - * ] - * }; - * ``` - */ -export interface Specification extends Extension { - /** - * This string MUST be the version number of the OpenAPI Specification that the - * OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret - * the OpenAPI document. This is not related to the API `info.version` string. - * This field is required. - * - * @example "3.1.0" - * @example "3.1.1" - */ - openapi: string - - /** - * Provides metadata about the API. The metadata MAY be used by tooling as required. - * This field is required. - * - * @example { title: "Pet Store API", version: "1.0.0" } - */ - info: Info - - /** - * The default value for the `$schema` keyword within Schema Objects contained - * within this OAS document. This MUST be in the form of a URI. - * - * @example "https://json-schema.org/draft/2020-12/schema" - */ - jsonSchemaDialect?: string - - /** - * An array of Server Objects, which provide connectivity information to a target - * server. If the `servers` property is not provided, or is an empty array, the - * default value would be a Server Object with a `url` value of `/`. - * - * @example [{ url: "https://api.example.com/v1", description: "The production API server" }] - */ - servers?: Server[] - - /** - * The available paths and operations for the API. - * - * @example { "/pets": { "get": { "summary": "List all pets", "responses": { "200": { "description": "A list of pets" } } } } } - */ - paths?: Paths - - /** - * The incoming webhooks that MAY be received as part of this API and that the - * API consumer MAY choose to implement. Closely related to the `callbacks` feature, - * this section describes requests initiated other than by an API call, for example - * by an out of band registration. - * - * @example { "newPet": { "post": { "requestBody": { "description": "Information about a new pet" } } } } - */ - webhooks?: Record // Will be properly typed when webhook types are created - - /** - * An element to hold various schemas for the document. - * - * @example { schemas: { Pet: { type: "object", properties: { id: { type: "integer" } } } } } - */ - components?: Components - - /** - * A declaration of which security mechanisms can be used across the API. The list - * of values includes alternative security requirement objects that can be used. - * Only one of the security requirement objects need to be satisfied to authorize - * a request. Individual operations can override this definition. - * - * @example [{ "api_key": [] }] - */ - security?: SecurityRequirement[] - - /** - * A list of tags used by the document with additional metadata. The order of the - * tags can be used to reflect on their order by the parsing tools. Not all tags - * that are used by the Operation Object must be declared. The tags that are not - * declared MAY be organized randomly or based on the tools' logic. Each tag name - * in the list MUST be unique. - * - * @example [{ name: "pets", description: "Pet store operations" }] - */ - tags?: Tag[] - - /** - * Additional external documentation. - * - * @example { description: "Find out more about our API", url: "https://example.com/docs" } - */ - externalDocs?: ExternalDocumentation -} diff --git a/3.1.x/xml.ts b/3.1.x/xml.ts deleted file mode 100644 index 560e3d1..0000000 --- a/3.1.x/xml.ts +++ /dev/null @@ -1,117 +0,0 @@ -import type { Extension } from "./extensions" - -/** - * ----- - * XML Object - * ----- - * - * A metadata object that allows for more fine-tuned XML model definitions. - * - * When using arrays, XML element names are not inferred (for singular/plural forms) - * and the `name` property SHOULD be used to add that information. - * - * | Version | Reference | - * |---|-----| - * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#xml-object | OpenAPI 3.1.1 XML Object} | - * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#xml-object | OpenAPI 3.1.0 XML Object} | - * - * ----- - * Fields - * ----- - * - * @key `name` - Optional Replaces the name of the element/attribute used for the described schema property - * @key `namespace` - Optional The URI of the namespace definition - * @key `prefix` - Optional The prefix to be used for the name - * @key `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element - * @key `wrapped` - Optional MAY be used only for an array definition. Signifies whether the array is wrapped - * @key `x-${string}` - Specification Extensions - * - * @note - * All fields are optional. - * - * ----- - * Examples - * ----- - * - * @example (simple XML): - * ```ts - * const xml: XML = { - * name: "user" - * }; - * ``` - * - * @example (XML with namespace): - * ```ts - * const xml: XML = { - * name: "user", - * namespace: "http://example.com/schema/user", - * prefix: "user" - * }; - * ``` - * - * @example (XML attribute): - * ```ts - * const xml: XML = { - * name: "id", - * attribute: true - * }; - * ``` - * - * @example (wrapped array): - * ```ts - * const xml: XML = { - * name: "users", - * wrapped: true - * }; - * ``` - */ -export interface XML extends Extension { - /** - * Replaces the name of the element/attribute used for the described schema property. - * When defined within the Items Object (items), it will affect the name of the individual - * XML elements within the list. When defined alongside type being array (outside the items), - * it will affect the wrapping element and only if wrapped is true. If wrapped is false, - * it will be ignored. - * - * @example "user" - * @example "id" - * @example "users" - */ - name?: string - - /** - * The URI of the namespace definition. This MUST be in the form of an absolute URI. - * - * @example "http://example.com/schema/user" - * @example "http://www.w3.org/XML/1998/namespace" - */ - namespace?: string - - /** - * The prefix to be used for the name. - * - * @example "user" - * @example "xml" - */ - prefix?: string - - /** - * Declares whether the property definition translates to an attribute instead of an element. - * Default value is false. - * - * @example true - * @example false - */ - attribute?: boolean - - /** - * MAY be used only for an array definition. Signifies whether the array is wrapped - * (for example, ``) or unwrapped - * (for example, ``). Default value is false. The definition takes effect - * only when defined alongside type being array (outside the items). - * - * @example true - * @example false - */ - wrapped?: boolean -} diff --git a/3.1.x/3.1.0.md b/3.1/3.1.0.md similarity index 100% rename from 3.1.x/3.1.0.md rename to 3.1/3.1.0.md diff --git a/3.1.x/3.1.1.md b/3.1/3.1.1.md similarity index 100% rename from 3.1.x/3.1.1.md rename to 3.1/3.1.1.md diff --git a/3.1/components.ts b/3.1/components.ts new file mode 100644 index 0000000..2c65bdd --- /dev/null +++ b/3.1/components.ts @@ -0,0 +1,143 @@ +import type { Extension } from "./extensions"; +import type { + Callback, + Example, + Header, + Link, + Parameter, + PathItemObject, + RequestBody, + Response, +} from "./paths"; +import type { Reference } from "./references"; +import type { Schema } from "./schema"; +import type { SecurityScheme } from "./security"; + +/** + * ----- + * Components Object + * ----- + * + * Holds a set of reusable objects for different aspects of the OAS. All objects defined + * within the components object will have no effect on the API unless they are explicitly + * referenced from properties outside the components object. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#components-object | OpenAPI 3.1.0 Components Object} | + * + * ----- + * Fields + * ----- + * + * @property `schemas` - An object to hold reusable Schema Objects + * @property `responses` - An object to hold reusable Response Objects + * @property `parameters` - An object to hold reusable Parameter Objects + * @property `examples` - An object to hold reusable Example Objects + * @property `requestBodies` - An object to hold reusable Request Body Objects + * @property `headers` - An object to hold reusable Header Objects + * @property `securitySchemes` - An object to hold reusable Security Scheme Objects + * @property `links` - An object to hold reusable Link Objects + * @property `callbacks` - An object to hold reusable Callback Objects + * @property `pathItems` - An object to hold reusable Path Item Objects + * @property `x-${string}` - Specification Extensions + * + * @note + * All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. + * + * ----- + * Examples + * ----- + * + * @example (simple components): + * ```ts + * const components: Components = { + * schemas: { + * User: { + * type: "object", + * properties: { + * id: { type: "integer", format: "int64" }, + * name: { type: "string" } + * } + * } + * }, + * responses: { + * NotFound: { + * description: "Resource not found" + * } + * } + * }; + * ``` + */ +export interface Components extends Extension { + /** + * An object to hold reusable Schema Objects. + * + * @example { User: { type: "object", properties: { id: { type: "integer" } } } } + */ + schemas?: Record; + + /** + * An object to hold reusable Response Objects. + * + * @example { NotFound: { description: "Resource not found" } } + */ + responses?: Record; + + /** + * An object to hold reusable Parameter Objects. + * + * @example { UserId: { name: "userId", in: "path", required: true, schema: { type: "string" } } } + */ + parameters?: Record; + + /** + * An object to hold reusable Example Objects. + * + * @example { UserExample: { value: { id: 1, name: "John Doe" } } } + */ + examples?: Record; + + /** + * An object to hold reusable Request Body Objects. + * + * @example { UserRequestBody: { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } } + */ + requestBodies?: Record; + + /** + * An object to hold reusable Header Objects. + * + * @example { RateLimit: { description: "Rate limit per hour", schema: { type: "integer" } } } + */ + headers?: Record; + + /** + * An object to hold reusable Security Scheme Objects. + * + * @example { ApiKeyAuth: { type: "apiKey", in: "header", name: "X-API-KEY" } } + */ + securitySchemes?: Record; + + /** + * An object to hold reusable Link Objects. + * + * @example { UserOrders: { operationId: "getOrdersByUserId", parameters: { userId: "$response.body#/id" } } } + */ + links?: Record; + + /** + * An object to hold reusable Callback Objects. + * + * @example { UserCreatedCallback: { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "User created event" } } } } } + */ + callbacks?: Record; + + /** + * An object to hold reusable Path Item Objects. + * + * @example { UserPath: { get: { summary: "Get user by ID" } } } + */ + pathItems?: Record; +} diff --git a/3.1/data-types/array.ts b/3.1/data-types/array.ts new file mode 100644 index 0000000..8e93331 --- /dev/null +++ b/3.1/data-types/array.ts @@ -0,0 +1,210 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Array Schema + * ----- + * + * A schema for array values. Includes array-specific validation properties + * that are only valid when `type: "array"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "array"` - Required The type identifier for array schemas + * @property `items` - Optional Schema for array items + * @property `prefixItems` - Optional Schema for array items at specific positions + * @property `contains` - Optional Schema that array must contain at least one item matching + * @property `minContains` - Optional Minimum number of items that must match contains + * @property `maxContains` - Optional Maximum number of items that must match contains + * @property `minItems` - Optional Minimum number of items in the array + * @property `maxItems` - Optional Maximum number of items in the array + * @property `uniqueItems` - Optional Whether array items must be unique + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "array". + * + * ----- + * Examples + * ----- + * + * @example (basic array): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" } + * }; + * ``` + * + * @example (array with validation): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" }, + * minItems: 1, + * maxItems: 10, + * uniqueItems: true + * }; + * ``` + * + * @example (array with prefixItems): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * prefixItems: [ + * { type: "string" }, + * { type: "number" } + * ] + * }; + * ``` + * + * @example (array with contains): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" }, + * contains: { type: "string", enum: ["admin"] }, + * minContains: 1 + * }; + * ``` + */ +export interface ArraySchema extends Extension { + /** + * The type identifier for array schemas. + * Must be "array". + */ + type: "array"; + + /** + * The schema for array items. + * All items in the array must conform to this schema. + * + * Example: `{ type: "string" }` + */ + items?: unknown; + + /** + * The schema for array items at specific positions. + * Items at position i must conform to the schema at index i. + * + * Example: `[{ type: "string" }, { type: "number" }]` + */ + prefixItems?: unknown[]; + + /** + * The schema that the array must contain at least one item matching. + * At least one item in the array must conform to this schema. + * + * Example: `{ type: "string", enum: ["admin"] }` + */ + contains?: unknown; + + /** + * The minimum number of items that must match the contains schema. + * Must be a non-negative integer. + * + * Example: `1` + */ + minContains?: number; + + /** + * The maximum number of items that must match the contains schema. + * Must be a non-negative integer. + * + * Example: `5` + */ + maxContains?: number; + + /** + * The minimum number of items in the array. + * Must be a non-negative integer. + * + * Example: `1` + */ + minItems?: number; + + /** + * The maximum number of items in the array. + * Must be a non-negative integer. + * + * Example: `10` + */ + maxItems?: number; + + /** + * Whether array items must be unique. + * If true, all items in the array must be unique. + * + * Example: `true` + */ + uniqueItems?: boolean; + + /** + * An array of allowed values for the array. + * The value must be one of the values in this array. + * + * Example: `[["a", "b"], ["c", "d"]]` + */ + enum?: unknown[]; + + /** + * A single allowed value for the array. + * The value must be exactly this value. + * + * Example: `["a", "b"]` + */ + const?: unknown; + + /** + * An example value for the array. + * This is for documentation purposes only. + * + * Example: `["a", "b"]` + */ + example?: unknown[]; + + /** + * An array of example values for the array. + * These are for documentation purposes only. + * + * Example: `[["a", "b"], ["c", "d"]]` + */ + examples?: unknown[][]; + + /** + * The default value for the array. + * This value will be used if no value is provided. + * + * Example: `[]` + */ + default?: unknown[]; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User Tags"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"Array of user tags"` + */ + description?: string; +} diff --git a/3.1/data-types/boolean.ts b/3.1/data-types/boolean.ts new file mode 100644 index 0000000..79e8d50 --- /dev/null +++ b/3.1/data-types/boolean.ts @@ -0,0 +1,129 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Boolean Schema + * ----- + * + * A schema for boolean values. Includes common validation properties + * that are only valid when `type: "boolean"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "boolean"` - Required The type identifier for boolean schemas + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "boolean". + * + * ----- + * Examples + * ----- + * + * @example (basic boolean): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean" + * }; + * ``` + * + * @example (boolean with default): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * default: false + * }; + * ``` + * + * @example (boolean with enum): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * enum: [true, false] + * }; + * ``` + * + * @example (boolean with const): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * const: true + * }; + * ``` + */ +export interface BooleanSchema extends Extension { + /** + * The type identifier for boolean schemas. + * Must be "boolean". + */ + type: "boolean"; + + /** + * An array of allowed values for the boolean. + * The value must be one of the values in this array. + * + * Example: `[true, false]` + */ + enum?: boolean[]; + + /** + * A single allowed value for the boolean. + * The value must be exactly this value. + * + * Example: `true` + */ + const?: boolean; + + /** + * An example value for the boolean. + * This is for documentation purposes only. + * + * Example: `true` + */ + example?: boolean; + + /** + * An array of example values for the boolean. + * These are for documentation purposes only. + * + * Example: `[true, false]` + */ + examples?: boolean[]; + + /** + * The default value for the boolean. + * This value will be used if no value is provided. + * + * Example: `false` + */ + default?: boolean; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"Is Active"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"Whether the user is active"` + */ + description?: string; +} diff --git a/3.1/data-types/composition.ts b/3.1/data-types/composition.ts new file mode 100644 index 0000000..dbc8a5c --- /dev/null +++ b/3.1/data-types/composition.ts @@ -0,0 +1,197 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Composition Schema + * ----- + * + * A schema that uses composition keywords (allOf, anyOf, oneOf, not). + * These keywords are mutually exclusive with $ref, but otherwise can + * appear with any validation keywords. This schema type supports + * advanced JSON Schema 2020-12 features like conditional schemas. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `allOf` - Optional Array of schemas that must all be satisfied + * @property `anyOf` - Optional Array of schemas where at least one must be satisfied + * @property `oneOf` - Optional Array of schemas where exactly one must be satisfied + * @property `not` - Optional Schema that must not be satisfied + * @property `if` - Optional Schema for conditional validation + * @property `then` - Optional Schema to apply if if condition is met + * @property `else` - Optional Schema to apply if if condition is not met + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * Composition keywords are mutually exclusive with $ref. At least one composition + * keyword must be present. The `if`/`then`/`else` keywords work together for + * conditional validation. + * + * ----- + * Examples + * ----- + * + * @example (allOf composition): + * ```ts + * const compositionSchema: CompositionSchema = { + * allOf: [ + * { type: "object", properties: { name: { type: "string" } } }, + * { type: "object", properties: { age: { type: "number" } } } + * ] + * }; + * ``` + * + * @example (anyOf composition): + * ```ts + * const compositionSchema: CompositionSchema = { + * anyOf: [ + * { type: "string" }, + * { type: "number" } + * ] + * }; + * ``` + * + * @example (oneOf composition): + * ```ts + * const compositionSchema: CompositionSchema = { + * oneOf: [ + * { type: "string", enum: ["active"] }, + * { type: "string", enum: ["inactive"] } + * ] + * }; + * ``` + * + * @example (conditional schema): + * ```ts + * const compositionSchema: CompositionSchema = { + * if: { type: "object", properties: { type: { const: "user" } } }, + * then: { type: "object", properties: { name: { type: "string" } } }, + * else: { type: "object", properties: { id: { type: "string" } } } + * }; + * ``` + */ +export interface CompositionSchema extends Extension { + /** + * An array of schemas that must all be satisfied. + * The value must conform to all schemas in the array. + * + * Example: `[{ type: "object" }, { properties: { name: { type: "string" } } }]` + */ + allOf?: unknown[]; + + /** + * An array of schemas where at least one must be satisfied. + * The value must conform to at least one schema in the array. + * + * Example: `[{ type: "string" }, { type: "number" }]` + */ + anyOf?: unknown[]; + + /** + * An array of schemas where exactly one must be satisfied. + * The value must conform to exactly one schema in the array. + * + * Example: `[{ type: "string" }, { type: "number" }]` + */ + oneOf?: unknown[]; + + /** + * A schema that must not be satisfied. + * The value must not conform to this schema. + * + * Example: `{ type: "string" }` + */ + not?: unknown; + + /** + * A schema for conditional validation. + * Used with `then` and `else` for conditional logic. + * + * Example: `{ type: "object", properties: { type: { const: "user" } } }` + */ + if?: unknown; + + /** + * A schema to apply if the `if` condition is met. + * The value must conform to this schema if the `if` schema is satisfied. + * + * Example: `{ type: "object", properties: { name: { type: "string" } } }` + */ + then?: unknown; + + /** + * A schema to apply if the `if` condition is not met. + * The value must conform to this schema if the `if` schema is not satisfied. + * + * Example: `{ type: "object", properties: { id: { type: "string" } } }` + */ + else?: unknown; + + /** + * An array of allowed values. + * The value must be one of the values in this array. + * + * Example: `["active", "inactive"]` + */ + enum?: unknown[]; + + /** + * A single allowed value. + * The value must be exactly this value. + * + * Example: `"active"` + */ + const?: unknown; + + /** + * An example value for the composition. + * This is for documentation purposes only. + * + * Example: `"example"` + */ + example?: unknown; + + /** + * An array of example values. + * These are for documentation purposes only. + * + * Example: `["example1", "example2"]` + */ + examples?: unknown[]; + + /** + * The default value. + * This value will be used if no value is provided. + * + * Example: `"default"` + */ + default?: unknown; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"Composed Schema"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"A schema composed of multiple schemas"` + */ + description?: string; +} diff --git a/3.1/data-types/index.ts b/3.1/data-types/index.ts new file mode 100644 index 0000000..c243852 --- /dev/null +++ b/3.1/data-types/index.ts @@ -0,0 +1,9 @@ +export type { ArraySchema } from "./array"; +export type { BooleanSchema } from "./boolean"; +export type { CompositionSchema } from "./composition"; +export type { IntegerSchema } from "./integer"; +export type { NullSchema } from "./null"; +export type { NumberSchema } from "./number"; +export type { ObjectSchema } from "./object"; +export type { ReferenceSchema } from "./reference"; +export type { StringSchema } from "./string"; diff --git a/3.1/data-types/integer.ts b/3.1/data-types/integer.ts new file mode 100644 index 0000000..11f3a94 --- /dev/null +++ b/3.1/data-types/integer.ts @@ -0,0 +1,186 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Integer Schema + * ----- + * + * A schema for integer values. Includes integer-specific validation properties + * that are only valid when `type: "integer"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "integer"` - Required The type identifier for integer schemas + * @property `format` - Optional The format of the integer + * @property `multipleOf` - Optional Integer must be a multiple of this value + * @property `maximum` - Optional Maximum value (inclusive) + * @property `minimum` - Optional Minimum value (inclusive) + * @property `exclusiveMaximum` - Optional Maximum value (exclusive) + * @property `exclusiveMinimum` - Optional Minimum value (exclusive) + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "integer". + * + * ----- + * Examples + * ----- + * + * @example (basic integer): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer" + * }; + * ``` + * + * @example (integer with format and validation): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * format: "int32", + * minimum: 0, + * maximum: 100 + * }; + * ``` + * + * @example (integer with multipleOf): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * multipleOf: 5 + * }; + * ``` + * + * @example (integer with exclusive bounds): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * exclusiveMinimum: 0, + * exclusiveMaximum: 100 + * }; + * ``` + */ +export interface IntegerSchema extends Extension { + /** + * The type identifier for integer schemas. + * Must be "integer". + */ + type: "integer"; + + /** + * The format of the integer. + * See OpenAPI 3.1.x Data Type Formats for further details. + * + * Example: `"int32"`, `"int64"` + */ + format?: string; + + /** + * The integer must be a multiple of this value. + * Must be a positive integer. + * + * Example: `5` + */ + multipleOf?: number; + + /** + * The maximum value of the integer (inclusive). + * The integer must be less than or equal to this value. + * + * Example: `100` + */ + maximum?: number; + + /** + * The minimum value of the integer (inclusive). + * The integer must be greater than or equal to this value. + * + * Example: `0` + */ + minimum?: number; + + /** + * The maximum value of the integer (exclusive). + * The integer must be less than this value. + * + * Example: `100` + */ + exclusiveMaximum?: number; + + /** + * The minimum value of the integer (exclusive). + * The integer must be greater than this value. + * + * Example: `0` + */ + exclusiveMinimum?: number; + + /** + * An array of allowed values for the integer. + * The value must be one of the values in this array. + * + * Example: `[1, 2, 3, 4, 5]` + */ + enum?: number[]; + + /** + * A single allowed value for the integer. + * The value must be exactly this value. + * + * Example: `42` + */ + const?: number; + + /** + * An example value for the integer. + * This is for documentation purposes only. + * + * Example: `42` + */ + example?: number; + + /** + * An array of example values for the integer. + * These are for documentation purposes only. + * + * Example: `[1, 2, 3]` + */ + examples?: number[]; + + /** + * The default value for the integer. + * This value will be used if no value is provided. + * + * Example: `0` + */ + default?: number; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User ID"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"The unique identifier of the user"` + */ + description?: string; +} diff --git a/3.1/data-types/null.ts b/3.1/data-types/null.ts new file mode 100644 index 0000000..0c45564 --- /dev/null +++ b/3.1/data-types/null.ts @@ -0,0 +1,108 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Null Schema + * ----- + * + * A schema that represents the null value type. This is part of the JSON Schema + * specification and is supported in OpenAPI 3.1.x. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Required The type identifier for null schemas + * @property `title` - Optional A short title for the schema + * @property `description` - Optional A description of the schema + * @property `default` - Optional The default value for the schema + * @property `examples` - Optional An array of example values + * @property `enum` - Optional An enumeration of allowed values + * @property `const` - Optional A constant allowed value + * @property `x-${string}` - Specification Extensions + * + * @note + * The `type` field must be "null". This schema type represents the null value. + * + * ----- + * Examples + * ----- + * + * @example (basic null schema): + * ```ts + * const nullSchema: NullSchema = { + * type: "null" + * }; + * ``` + * + * @example (null schema with description): + * ```ts + * const nullSchema: NullSchema = { + * type: "null", + * description: "Represents a null value" + * }; + * ``` + * + * @example (null schema with const): + * ```ts + * const nullSchema: NullSchema = { + * type: "null", + * const: null + * }; + * ``` + */ +export interface NullSchema extends Extension { + /** + * The type identifier for null schemas. This field is required. + * + * @example "null" + */ + type: "null"; + + /** + * A short title for the schema. + * + * @example "Null Value" + */ + title?: string; + + /** + * A description of the schema. CommonMark syntax MAY be used for rich text representation. + * + * @example "Represents a null value" + */ + description?: string; + + /** + * The default value for the schema. + * + * @example null + */ + default?: null; + + /** + * An array of example values. + * + * @example [null] + */ + examples?: null[]; + + /** + * An enumeration of allowed values. For null schemas, this should contain only null. + * + * @example [null] + */ + enum?: null[]; + + /** + * A constant allowed value. For null schemas, this should be null. + * + * @example null + */ + const?: null; +} diff --git a/3.1/data-types/number.ts b/3.1/data-types/number.ts new file mode 100644 index 0000000..b0dbdb0 --- /dev/null +++ b/3.1/data-types/number.ts @@ -0,0 +1,186 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Number Schema + * ----- + * + * A schema for number values. Includes number-specific validation properties + * that are only valid when `type: "number"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "number"` - Required The type identifier for number schemas + * @property `format` - Optional The format of the number + * @property `multipleOf` - Optional Number must be a multiple of this value + * @property `maximum` - Optional Maximum value (inclusive) + * @property `minimum` - Optional Minimum value (inclusive) + * @property `exclusiveMaximum` - Optional Maximum value (exclusive) + * @property `exclusiveMinimum` - Optional Minimum value (exclusive) + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "number". + * + * ----- + * Examples + * ----- + * + * @example (basic number): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number" + * }; + * ``` + * + * @example (number with format and validation): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * format: "float", + * minimum: 0, + * maximum: 100 + * }; + * ``` + * + * @example (number with multipleOf): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * multipleOf: 0.5 + * }; + * ``` + * + * @example (number with exclusive bounds): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * exclusiveMinimum: 0, + * exclusiveMaximum: 100 + * }; + * ``` + */ +export interface NumberSchema extends Extension { + /** + * The type identifier for number schemas. + * Must be "number". + */ + type: "number"; + + /** + * The format of the number. + * See OpenAPI 3.1.x Data Type Formats for further details. + * + * Example: `"float"`, `"double"` + */ + format?: string; + + /** + * The number must be a multiple of this value. + * Must be a positive number. + * + * Example: `0.5` + */ + multipleOf?: number; + + /** + * The maximum value of the number (inclusive). + * The number must be less than or equal to this value. + * + * Example: `100` + */ + maximum?: number; + + /** + * The minimum value of the number (inclusive). + * The number must be greater than or equal to this value. + * + * Example: `0` + */ + minimum?: number; + + /** + * The maximum value of the number (exclusive). + * The number must be less than this value. + * + * Example: `100` + */ + exclusiveMaximum?: number; + + /** + * The minimum value of the number (exclusive). + * The number must be greater than this value. + * + * Example: `0` + */ + exclusiveMinimum?: number; + + /** + * An array of allowed values for the number. + * The value must be one of the values in this array. + * + * Example: `[1, 2, 3, 4, 5]` + */ + enum?: number[]; + + /** + * A single allowed value for the number. + * The value must be exactly this value. + * + * Example: `42` + */ + const?: number; + + /** + * An example value for the number. + * This is for documentation purposes only. + * + * Example: `42` + */ + example?: number; + + /** + * An array of example values for the number. + * These are for documentation purposes only. + * + * Example: `[1.5, 2.7, 3.14]` + */ + examples?: number[]; + + /** + * The default value for the number. + * This value will be used if no value is provided. + * + * Example: `0` + */ + default?: number; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"Price"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"The price of the item"` + */ + description?: string; +} diff --git a/3.1/data-types/object.ts b/3.1/data-types/object.ts new file mode 100644 index 0000000..4a4cc79 --- /dev/null +++ b/3.1/data-types/object.ts @@ -0,0 +1,225 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Object Schema + * ----- + * + * A schema for object values. Includes object-specific validation properties + * that are only valid when `type: "object"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "object"` - Required The type identifier for object schemas + * @property `properties` - Optional Map of property names to their schemas + * @property `required` - Optional Array of required property names + * @property `additionalProperties` - Optional Schema for additional properties + * @property `patternProperties` - Optional Map of regex patterns to schemas + * @property `propertyNames` - Optional Schema for property names + * @property `minProperties` - Optional Minimum number of properties + * @property `maxProperties` - Optional Maximum number of properties + * @property `dependentRequired` - Optional Map of property names to arrays of required properties + * @property `dependentSchemas` - Optional Map of property names to schemas + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "object". + * + * ----- + * Examples + * ----- + * + * @example (basic object): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * } + * }; + * ``` + * + * @example (object with required properties): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * }, + * required: ["name"] + * }; + * ``` + * + * @example (object with additionalProperties): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" } + * }, + * additionalProperties: { type: "string" } + * }; + * ``` + * + * @example (object with patternProperties): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * patternProperties: { + * "^S_": { type: "string" } + * } + * }; + * ``` + */ +export interface ObjectSchema extends Extension { + /** + * The type identifier for object schemas. + * Must be "object". + */ + type: "object"; + + /** + * A map of property names to their schemas. + * Each property in the object must conform to its corresponding schema. + * + * Example: `{ name: { type: "string" }, age: { type: "number" } }` + */ + properties?: Record; + + /** + * An array of required property names. + * These properties must be present in the object. + * + * Example: `["name", "email"]` + */ + required?: string[]; + + /** + * The schema for additional properties not defined in properties. + * If false, no additional properties are allowed. + * If true, any additional properties are allowed. + * If a schema, additional properties must conform to this schema. + * + * Example: `{ type: "string" }` or `false` or `true` + */ + additionalProperties?: unknown | boolean; + + /** + * A map of regex patterns to schemas. + * Properties whose names match a pattern must conform to the corresponding schema. + * + * Example: `{ "^S_": { type: "string" } }` + */ + patternProperties?: Record; + + /** + * The schema for property names. + * All property names in the object must conform to this schema. + * + * Example: `{ type: "string", pattern: "^[A-Za-z][A-Za-z0-9]*$" }` + */ + propertyNames?: unknown; + + /** + * The minimum number of properties in the object. + * Must be a non-negative integer. + * + * Example: `1` + */ + minProperties?: number; + + /** + * The maximum number of properties in the object. + * Must be a non-negative integer. + * + * Example: `10` + */ + maxProperties?: number; + + /** + * A map of property names to arrays of required properties. + * If a property is present, the properties in its array must also be present. + * + * Example: `{ credit_card: ["billing_address"] }` + */ + dependentRequired?: Record; + + /** + * A map of property names to schemas. + * If a property is present, the object must conform to the corresponding schema. + * + * Example: `{ credit_card: { type: "object", properties: { number: { type: "string" } } } }` + */ + dependentSchemas?: Record; + + /** + * An array of allowed values for the object. + * The value must be one of the values in this array. + * + * Example: `[{ name: "John" }, { name: "Jane" }]` + */ + enum?: Record[]; + + /** + * A single allowed value for the object. + * The value must be exactly this value. + * + * Example: `{ name: "John" }` + */ + const?: Record; + + /** + * An example value for the object. + * This is for documentation purposes only. + * + * Example: `{ name: "John" }` + */ + example?: Record; + + /** + * An array of example values for the object. + * These are for documentation purposes only. + * + * Example: `[{ name: "John", age: 30 }]` + */ + examples?: Record[]; + + /** + * The default value for the object. + * This value will be used if no value is provided. + * + * Example: `{}` + */ + default?: Record; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"A user object"` + */ + description?: string; +} diff --git a/3.1.x/data-types/reference.ts b/3.1/data-types/reference.ts similarity index 66% rename from 3.1.x/data-types/reference.ts rename to 3.1/data-types/reference.ts index 1be6869..a8a6aa0 100644 --- a/3.1.x/data-types/reference.ts +++ b/3.1/data-types/reference.ts @@ -1,4 +1,4 @@ -import type { Extension } from "../extensions" +import type { Extension } from "../extensions"; /** * ----- @@ -18,9 +18,9 @@ import type { Extension } from "../extensions" * Fields * ----- * - * @key `$ref` - Required A reference to a schema - * @key `description` - Optional A description of the referenced schema - * @key `x-${string}` - Specification Extensions + * @property `$ref` - Required A reference to a schema + * @property `description` - Optional A description of the referenced schema + * @property `x-${string}` - Specification Extensions * * @note * When `$ref` is present, no other properties except `description` and extensions are allowed. @@ -53,19 +53,19 @@ import type { Extension } from "../extensions" * ``` */ export interface ReferenceSchema extends Extension { - /** - * A reference to a schema. This MUST be in the form of a URI. - * When present, no other properties except `description` and extensions are allowed. - * - * Example: `"#/components/schemas/User"` - */ - $ref: string + /** + * A reference to a schema. This MUST be in the form of a URI. + * When present, no other properties except `description` and extensions are allowed. + * + * Example: `"#/components/schemas/User"` + */ + $ref: string; - /** - * A description of the referenced schema. - * CommonMark syntax MAY be used for rich text representation. - * - * Example: `"Reference to a user schema"` - */ - description?: string + /** + * A description of the referenced schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"Reference to a user schema"` + */ + description?: string; } diff --git a/3.1/data-types/string.ts b/3.1/data-types/string.ts new file mode 100644 index 0000000..10680be --- /dev/null +++ b/3.1/data-types/string.ts @@ -0,0 +1,194 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * String Schema + * ----- + * + * A schema for string values. Includes string-specific validation properties + * that are only valid when `type: "string"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#data-types | OpenAPI 3.1.1 Data Types} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#data-types | OpenAPI 3.1.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "string"` - Required The type identifier for string schemas + * @property `format` - Optional The format of the string + * @property `maxLength` - Optional Maximum length of the string + * @property `minLength` - Optional Minimum length of the string + * @property `pattern` - Optional Regular expression pattern + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `contentMediaType` - Optional The media type of the content + * @property `contentEncoding` - Optional The encoding of the content + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "string". + * + * ----- + * Examples + * ----- + * + * @example (basic string): + * ```ts + * const stringSchema: StringSchema = { + * type: "string" + * }; + * ``` + * + * @example (string with format and validation): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * format: "email", + * maxLength: 255, + * minLength: 5 + * }; + * ``` + * + * @example (string with enum): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * enum: ["active", "inactive", "pending"] + * }; + * ``` + * + * @example (string with pattern): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * pattern: "^[A-Za-z0-9]+$" + * }; + * ``` + * + * @example (string with content encoding): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * contentMediaType: "image/png", + * contentEncoding: "base64" + * }; + * ``` + */ +export interface StringSchema extends Extension { + /** + * The type identifier for string schemas. + * Must be "string". + */ + type: "string"; + + /** + * The format of the string. + * See OpenAPI 3.1.x Data Type Formats for further details. + * + * Example: `"email"`, `"date-time"`, `"uuid"` + */ + format?: string; + + /** + * The maximum length of the string. + * Must be a non-negative integer. + * + * Example: `255` + */ + maxLength?: number; + + /** + * The minimum length of the string. + * Must be a non-negative integer. + * + * Example: `1` + */ + minLength?: number; + + /** + * A regular expression pattern that the string must match. + * Should be a valid ECMA 262 regular expression. + * + * Example: `"^[A-Za-z0-9]+$"` + */ + pattern?: string; + + /** + * An array of allowed values for the string. + * The value must be one of the values in this array. + * + * Example: `["active", "inactive", "pending"]` + */ + enum?: string[]; + + /** + * A single allowed value for the string. + * The value must be exactly this value. + * + * Example: `"active"` + */ + const?: string; + + /** + * An example value for the string. + * This is for documentation purposes only. + * + * Example: `"example@email.com"` + */ + example?: string; + + /** + * An array of example values for the string. + * These are for documentation purposes only. + * + * Example: `["example@email.com", "test@domain.com"]` + */ + examples?: string[]; + + /** + * The default value for the string. + * This value will be used if no value is provided. + * + * Example: `"default"` + */ + default?: string; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User Email"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"The email address of the user"` + */ + description?: string; + + /** + * The media type of the content. This is used to specify the media type + * of the content when the string represents encoded content. + * + * Example: `"image/png"`, `"application/json"` + */ + contentMediaType?: string; + + /** + * The encoding of the content. This is used to specify how the content + * is encoded when the string represents encoded content. + * + * Example: `"base64"`, `"base64url"`, `"quoted-printable"` + */ + contentEncoding?: string; +} diff --git a/3.1.x/extensions.ts b/3.1/extensions.ts similarity index 78% rename from 3.1.x/extensions.ts rename to 3.1/extensions.ts index e113622..447c3cd 100644 --- a/3.1.x/extensions.ts +++ b/3.1/extensions.ts @@ -19,7 +19,7 @@ * Fields * ----- * - * @key `x-${string}` - Specification Extensions + * @property `x-${string}` - Specification Extensions * * @note * All extension properties must start with `x-` and can contain any valid JSON value. @@ -51,13 +51,13 @@ * ``` */ export interface Extension { - /** - * Specification Extensions allow adding custom properties to OpenAPI objects. - * All extension properties must start with `x-` and can contain any valid JSON value. - * - * @example "x-custom-property" - * @example "x-internal-id" - * @example "x-codegen-settings" - */ - [key: `x-${string}`]: unknown + /** + * Specification Extensions allow adding custom properties to OpenAPI objects. + * All extension properties must start with `x-` and can contain any valid JSON value. + * + * @example "x-custom-property" + * @example "x-internal-id" + * @example "x-codegen-settings" + */ + [key: `x-${string}`]: unknown; } diff --git a/3.1.x/externalDocs.ts b/3.1/externalDocs.ts similarity index 57% rename from 3.1.x/externalDocs.ts rename to 3.1/externalDocs.ts index 9c9171d..4ebae54 100644 --- a/3.1.x/externalDocs.ts +++ b/3.1/externalDocs.ts @@ -1,4 +1,4 @@ -import type { Extension } from "./extensions" +import type { Extension } from "./extensions"; /** * ----- @@ -16,9 +16,9 @@ import type { Extension } from "./extensions" * Fields * ----- * - * @key `description` - Optional A short description of the target documentation - * @key `url` - Required The URL for the target documentation - * @key `x-${string}` - Specification Extensions + * @property `description` - Optional A short description of the target documentation + * @property `url` - Required The URL for the target documentation + * @property `x-${string}` - Specification Extensions * * @note * The `url` field is required. @@ -43,21 +43,21 @@ import type { Extension } from "./extensions" * ``` */ export interface ExternalDocumentation extends Extension { - /** - * A short description of the target documentation. CommonMark syntax MAY be used - * for rich text representation. - * - * @example "Find out more about our API" - * @example "Additional documentation for this endpoint" - */ - description?: string + /** + * A short description of the target documentation. CommonMark syntax MAY be used + * for rich text representation. + * + * @example "Find out more about our API" + * @example "Additional documentation for this endpoint" + */ + description?: string; - /** - * The URL for the target documentation. This field is required and MUST be in the - * format of a URL. - * - * @example "https://example.com/docs" - * @example "https://docs.example.com/api" - */ - url: string + /** + * The URL for the target documentation. This field is required and MUST be in the + * format of a URL. + * + * @example "https://example.com/docs" + * @example "https://docs.example.com/api" + */ + url: string; } diff --git a/3.1.x/index.ts b/3.1/index.ts similarity index 79% rename from 3.1.x/index.ts rename to 3.1/index.ts index 1626616..43c5343 100644 --- a/3.1.x/index.ts +++ b/3.1/index.ts @@ -1,53 +1,44 @@ /** * @fileoverview OpenAPI 3.1.x TypeScript Type Definitions - * + * * This module provides comprehensive TypeScript type definitions for OpenAPI 3.1.x specifications. * All types are fully documented with JSDoc comments and include links to the official OpenAPI * specification documentation. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1.html | OpenAPI 3.1.1 Specification} * @see {@link https://spec.openapis.org/oas/v3.1.0.html | OpenAPI 3.1.0 Specification} - * + * * @version 3.1.x * @since 1.0.0 */ /** - * Main OpenAPI specification document type. - * - * @see {@link https://spec.openapis.org/oas/v3.1.1#oas-document | OpenAPI 3.1.1 OAS Document} + * Reusable component types. + * + * @see {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object} */ -export type { Specification } from "./spec" +export type { Components } from "./components"; /** * Core extension and reference types. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1#specification-extensions | OpenAPI 3.1.1 Specification Extensions} * @see {@link https://spec.openapis.org/oas/v3.1.1#reference-object | OpenAPI 3.1.1 Reference Object} */ -export type { Extension } from "./extensions" -export type { Reference } from "./references" +export type { Extension } from "./extensions"; +export type { ExternalDocumentation } from "./externalDocs"; /** * API information and metadata types. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1#info-object | OpenAPI 3.1.1 Info Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#contact-object | OpenAPI 3.1.1 Contact Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#license-object | OpenAPI 3.1.1 License Object} */ -export type { Info, Contact, License } from "./info" - -/** - * Server configuration types. - * - * @see {@link https://spec.openapis.org/oas/v3.1.1#server-object | OpenAPI 3.1.1 Server Object} - * @see {@link https://spec.openapis.org/oas/v3.1.1#server-variable-object | OpenAPI 3.1.1 Server Variable Object} - */ -export type { Server, ServerVariable } from "./servers" - +export type { Contact, Info, License } from "./info"; /** * Path and operation definition types. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1#paths-object | OpenAPI 3.1.1 Paths Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#path-item-object | OpenAPI 3.1.1 Path Item Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#operation-object | OpenAPI 3.1.1 Operation Object} @@ -63,69 +54,79 @@ export type { Server, ServerVariable } from "./servers" * @see {@link https://spec.openapis.org/oas/v3.1.1#callback-object | OpenAPI 3.1.1 Callback Object} */ export type { - Paths, - PathItemObject, - Operation, - Parameter, - RequestBody, - Responses, - Response, - Header, - MediaType, - Encoding, - Example, - Link, - Callback -} from "./paths" - + Callback, + Encoding, + Example, + Header, + Link, + MediaType, + Operation, + Parameter, + PathItemObject, + Paths, + RequestBody, + Response, + Responses, +} from "./paths"; +export type { Reference } from "./references"; /** * Schema definition types based on JSON Schema Draft 2020-12. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} * @see {@link https://json-schema.org/draft/2020-12/json-schema-core.html | JSON Schema Draft 2020-12} */ export type { - Schema, - ReferenceSchema, - StringSchema, - NumberSchema, - IntegerSchema, - BooleanSchema, - ArraySchema, - ObjectSchema, - CompositionSchema, - Discriminator -} from "./schema" - -/** - * Reusable component types. - * - * @see {@link https://spec.openapis.org/oas/v3.1.1#components-object | OpenAPI 3.1.1 Components Object} - */ -export type { Components } from "./components" - + ArraySchema, + BooleanSchema, + CompositionSchema, + Discriminator, + IntegerSchema, + NumberSchema, + ObjectSchema, + ReferenceSchema, + Schema, + StringSchema, +} from "./schema"; /** * Security scheme and authentication types. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1#security-scheme-object | OpenAPI 3.1.1 Security Scheme Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#oauth-flows-object | OpenAPI 3.1.1 OAuth Flows Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#oauth-flow-object | OpenAPI 3.1.1 OAuth Flow Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#security-requirement-object | OpenAPI 3.1.1 Security Requirement Object} */ export type { - SecurityScheme, - OAuthFlows, - OAuthFlow, - SecurityRequirement -} from "./security" + OAuthFlow, + OAuthFlows, + SecurityRequirement, + SecurityScheme, +} from "./security"; +/** + * Server configuration types. + * + * @see {@link https://spec.openapis.org/oas/v3.1.1#server-object | OpenAPI 3.1.1 Server Object} + * @see {@link https://spec.openapis.org/oas/v3.1.1#server-variable-object | OpenAPI 3.1.1 Server Variable Object} + */ +export type { Server, ServerVariable } from "./servers"; +/** + * Main OpenAPI specification document type. + * + * @see {@link https://spec.openapis.org/oas/v3.1.1#oas-document | OpenAPI 3.1.1 OAS Document} + */ +export type { Specification } from "./spec"; /** * Utility and metadata types. - * + * * @see {@link https://spec.openapis.org/oas/v3.1.1#tag-object | OpenAPI 3.1.1 Tag Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#external-documentation-object | OpenAPI 3.1.1 External Documentation Object} * @see {@link https://spec.openapis.org/oas/v3.1.1#xml-object | OpenAPI 3.1.1 XML Object} */ -export type { Tag } from "./tags" -export type { ExternalDocumentation } from "./externalDocs" -export type { XML } from "./xml" +export type { Tag } from "./tags"; +/** + * Webhook definition types. + * + * @see {@link https://spec.openapis.org/oas/v3.1.1#webhooks-object | OpenAPI 3.1.1 Webhooks Object} + */ +export type { Webhooks } from "./webhooks"; +export type { XML } from "./xml"; diff --git a/3.1/info.ts b/3.1/info.ts new file mode 100644 index 0000000..eaecfdb --- /dev/null +++ b/3.1/info.ts @@ -0,0 +1,263 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Info Object + * ----- + * + * The object provides metadata about the API. The metadata MAY be used by tooling + * as required. The object may be extended with Specification Extensions. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#info-object | OpenAPI 3.1.1 Info Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#info-object | OpenAPI 3.1.0 Info Object} | + * + * ----- + * Fields + * ----- + * + * @property `title` - Required The title of the API + * @property `summary` - Optional A short summary of the API + * @property `description` - Optional A description of the API + * @property `termsOfService` - Optional A URL to the Terms of Service for the API + * @property `contact` - Optional The contact information for the exposed API + * @property `license` - Optional The license information for the exposed API + * @property `version` - Required The version of the OpenAPI document + * @property `x-${string}` - Specification Extensions + * + * @note + * The `title` and `version` fields are required. + * + * ----- + * Examples + * ----- + * + * @example (minimal info): + * ```ts + * const info: Info = { + * title: "Pet Store API", + * version: "1.0.0" + * }; + * ``` + * + * @example (complete info): + * ```ts + * const info: Info = { + * title: "Pet Store API", + * summary: "A sample API that uses a petstore as an example", + * description: "This is a sample server Petstore server.", + * termsOfService: "http://example.com/terms/", + * contact: { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }, + * license: { + * name: "Apache 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0.html" + * }, + * version: "1.0.0" + * }; + * ``` + */ +export interface Info extends Extension { + /** + * The title of the API. This field is required. + * + * @example "Pet Store API" + * @example "User Management API" + */ + title: string; + + /** + * A short summary of the API. + * + * @example "A sample API that uses a petstore as an example" + * @example "API for managing users and their data" + */ + summary?: string; + + /** + * A description of the API. CommonMark syntax MAY be used for rich text representation. + * + * @example "This is a sample server Petstore server." + * @example "This API provides endpoints for user management, authentication, and data operations." + */ + description?: string; + + /** + * A URL to the Terms of Service for the API. MUST be in the format of a URL. + * + * @example "http://example.com/terms/" + * @example "https://www.example.com/terms-of-service" + */ + termsOfService?: string; + + /** + * The contact information for the exposed API. + * + * @example { name: "API Support", email: "support@example.com" } + */ + contact?: Contact; + + /** + * The license information for the exposed API. + * + * @example { name: "Apache 2.0", url: "https://www.apache.org/licenses/LICENSE-2.0.html" } + */ + license?: License; + + /** + * The version of the OpenAPI document. This field is required. + * + * @example "1.0.0" + * @example "2.1.3" + */ + version: string; +} + +/** + * ----- + * Contact Object + * ----- + * + * Contact information for the exposed API. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#contact-object | OpenAPI 3.1.1 Contact Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#contact-object | OpenAPI 3.1.0 Contact Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Optional The identifying name of the contact person/organization + * @property `url` - Optional The URL pointing to the contact information + * @property `email` - Optional The email address of the contact person/organization + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. + * + * ----- + * Examples + * ----- + * + * @example (simple contact): + * ```ts + * const contact: Contact = { + * name: "API Support", + * email: "support@example.com" + * }; + * ``` + * + * @example (complete contact): + * ```ts + * const contact: Contact = { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }; + * ``` + */ +export interface Contact extends Extension { + /** + * The identifying name of the contact person/organization. + * + * @example "API Support" + * @example "Development Team" + */ + name?: string; + + /** + * The URL pointing to the contact information. MUST be in the format of a URL. + * + * @example "http://www.example.com/support" + * @example "https://example.com/contact" + */ + url?: string; + + /** + * The email address of the contact person/organization. MUST be in the format of an email address. + * + * @example "support@example.com" + * @example "dev@example.com" + */ + email?: string; +} + +/** + * ----- + * License Object + * ----- + * + * License information for the exposed API. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#license-object | OpenAPI 3.1.1 License Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#license-object | OpenAPI 3.1.0 License Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The license name used for the API + * @property `identifier` - Optional An SPDX license expression for the API + * @property `url` - Optional A URL to the license used for the API + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` field is required. Either `identifier` or `url` should be specified. + * + * ----- + * Examples + * ----- + * + * @example (with URL): + * ```ts + * const license: License = { + * name: "Apache 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0.html" + * }; + * ``` + * + * @example (with identifier): + * ```ts + * const license: License = { + * name: "Apache 2.0", + * identifier: "Apache-2.0" + * }; + * ``` + */ +export interface License extends Extension { + /** + * The license name used for the API. This field is required. + * + * @example "Apache 2.0" + * @example "MIT" + * @example "GPL-3.0" + */ + name: string; + + /** + * An SPDX license expression for the API. The `identifier` field is mutually + * exclusive of the `url` field. + * + * @example "Apache-2.0" + * @example "MIT" + * @example "GPL-3.0" + */ + identifier?: string; + + /** + * A URL to the license used for the API. MUST be in the format of a URL. + * The `url` field is mutually exclusive of the `identifier` field. + * + * @example "https://www.apache.org/licenses/LICENSE-2.0.html" + * @example "https://opensource.org/licenses/MIT" + */ + url?: string; +} diff --git a/3.1/paths.ts b/3.1/paths.ts new file mode 100644 index 0000000..9320393 --- /dev/null +++ b/3.1/paths.ts @@ -0,0 +1,1377 @@ +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +import type { Reference } from "./references"; +import type { Schema } from "./schema"; +import type { SecurityRequirement } from "./security"; +import type { Server } from "./servers"; +import type { ResponsesMap } from "./status"; + +/** + * ----- + * Paths Object + * ----- + * + * Holds the relative paths to the individual endpoints and their operations. + * The path is appended to the URL from the Server Object in order to construct + * the full URL. The Paths may be empty, due to ACL constraints. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#paths-object | OpenAPI 3.1.1 Paths Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#paths-object | OpenAPI 3.1.0 Paths Object} | + * + * ----- + * Fields + * ----- + * + * @property `/{path}` - A relative path to an individual endpoint + * @property `x-${string}` - Specification Extensions + * + * @note + * The path keys must start with `/` and can contain path parameters in `{brackets}`. + * + * ----- + * Examples + * ----- + * + * @example (simple paths): + * ```ts + * const paths: Paths = { + * "/pets": { + * "get": { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * } + * } + * }; + * ``` + */ +export type Paths = Record; + +/** + * ----- + * Path Item Object + * ----- + * + * Describes the operations available on a single path. A Path Item MAY be empty, + * due to ACL constraints. The path itself is still exposed to the documentation + * viewer but they will not know which operations and parameters are available. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#path-item-object | OpenAPI 3.1.1 Path Item Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#path-item-object | OpenAPI 3.1.0 Path Item Object} | + * + * ----- + * Fields + * ----- + * + * @property `summary` - Optional An optional, string summary, intended to apply to all operations in this path + * @property `description` - Optional An optional, string description, intended to apply to all operations in this path + * @property `get` - Optional A definition of a GET operation on this path + * @property `put` - Optional A definition of a PUT operation on this path + * @property `post` - Optional A definition of a POST operation on this path + * @property `delete` - Optional A definition of a DELETE operation on this path + * @property `options` - Optional A definition of an OPTIONS operation on this path + * @property `head` - Optional A definition of a HEAD operation on this path + * @property `patch` - Optional A definition of a PATCH operation on this path + * @property `trace` - Optional A definition of a TRACE operation on this path + * @property `servers` - Optional An alternative server array to service all operations in this path + * @property `parameters` - Optional A list of parameters that are applicable for all the operations described under this path + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. The HTTP methods are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (simple path item): + * ```ts + * const pathItem: PathItemObject = { + * "get": { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * } + * }; + * ``` + */ +export interface PathItemObject extends Extension { + /** + * An optional, string summary, intended to apply to all operations in this path. + * + * @example "Pet operations" + * @example "User management" + */ + summary?: string; + + /** + * An optional, string description, intended to apply to all operations in this path. + * CommonMark syntax MAY be used for rich text representation. + * + * @example "Operations related to pet management" + * @example "All user-related operations" + */ + description?: string; + + /** + * A definition of a GET operation on this path. + */ + get?: Operation; + + /** + * A definition of a PUT operation on this path. + */ + put?: Operation; + + /** + * A definition of a POST operation on this path. + */ + post?: Operation; + + /** + * A definition of a DELETE operation on this path. + */ + delete?: Operation; + + /** + * A definition of an OPTIONS operation on this path. + */ + options?: Operation; + + /** + * A definition of a HEAD operation on this path. + */ + head?: Operation; + + /** + * A definition of a PATCH operation on this path. + */ + patch?: Operation; + + /** + * A definition of a TRACE operation on this path. + */ + trace?: Operation; + + /** + * An alternative server array to service all operations in this path. + * + * @example [{ url: "https://api.example.com/v1" }] + */ + servers?: Server[]; + + /** + * A list of parameters that are applicable for all the operations described under + * this path. These parameters can be overridden at the operation level, but cannot + * be removed there. The list MUST NOT include duplicated parameters. A unique + * parameter is defined by a combination of a name and location. + * + * @example [{ name: "id", in: "path", required: true, schema: { type: "string" } }] + */ + parameters?: (Parameter | Reference)[]; +} + +/** + * ----- + * Operation Object + * ----- + * + * Describes a single API operation on a path. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#operation-object | OpenAPI 3.1.1 Operation Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#operation-object | OpenAPI 3.1.0 Operation Object} | + * + * ----- + * Fields + * ----- + * + * @property `tags` - Optional A list of tags for API documentation control + * @property `summary` - Optional A short summary of what the operation does + * @property `description` - Optional A verbose explanation of the operation behavior + * @property `externalDocs` - Optional Additional external documentation for this operation + * @property `operationId` - Optional Unique string used to identify the operation + * @property `parameters` - Optional A list of parameters that are applicable for this operation + * @property `requestBody` - Optional The request body applicable for this operation + * @property `responses` - Required The list of possible responses as they are returned from executing this operation + * @property `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation + * @property `deprecated` - Optional Declares this operation to be deprecated + * @property `security` - Optional A declaration of which security mechanisms can be used for this operation + * @property `servers` - Optional An alternative server array to service this operation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `responses` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple operation): + * ```ts + * const operation: Operation = { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * }; + * ``` + */ +export interface Operation extends Extension { + /** + * A list of tags for API documentation control. Tags can be used for logical + * grouping of operations by resources or any other qualifier. + * + * @example ["pets", "list"] + * @example ["users", "authentication"] + */ + tags?: string[]; + + /** + * A short summary of what the operation does. + * + * @example "List all pets" + * @example "Create a new user" + */ + summary?: string; + + /** + * A verbose explanation of the operation behavior. CommonMark syntax MAY be used + * for rich text representation. + * + * @example "Returns all pets from the system that the user has access to" + * @example "Creates a new user account with the provided information" + */ + description?: string; + + /** + * Additional external documentation for this operation. + * + * @example { description: "Find out more about pet operations", url: "https://example.com/docs/pets" } + */ + externalDocs?: ExternalDocumentation; + + /** + * Unique string used to identify the operation. The id MUST be unique among all + * operations described in the API. The operationId value is case-sensitive. + * + * @example "listPets" + * @example "createUser" + */ + operationId?: string; + + /** + * A list of parameters that are applicable for this operation. If a parameter + * is already defined at the Path Item, the new definition will override it but + * can never remove it. The list MUST NOT include duplicated parameters. + * + * @example [{ name: "limit", in: "query", schema: { type: "integer" } }] + */ + parameters?: (Parameter | Reference)[]; + + /** + * The request body applicable for this operation. The requestBody is only supported + * in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined + * semantics for request bodies. + * + * @example { description: "Pet to add to the store", content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } } + */ + requestBody?: RequestBody | Reference; + + /** + * The list of possible responses as they are returned from executing this operation. + * This field is required. + * + * @example { "200": { description: "A list of pets" }, "default": { description: "Unexpected error" } } + */ + responses: ResponsesMap; + + /** + * A map of possible out-of band callbacks related to the parent operation. The key + * is a unique identifier for the Callback Object. Each value in the map is a + * Callback Object that describes a request that may be initiated by the API + * provider and the expected responses. + * + * @example { "myCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "Callback payload" } } } } } + */ + callbacks?: Record; + + /** + * Declares this operation to be deprecated. Consumers SHOULD refrain from using + * the declared operation. Default value is false. + * + * @example true + * @example false + * @default false + */ + deprecated?: boolean; + + /** + * A declaration of which security mechanisms can be used for this operation. + * The list of values includes alternative security requirement objects that can + * be used. Only one of the security requirement objects need to be satisfied + * to authorize a request. + * + * @example [{ "petstore_auth": ["write:pets", "read:pets"] }] + */ + security?: SecurityRequirement[]; + + /** + * An alternative server array to service this operation. If an alternative + * server object is specified at the Path Item Object level, it will be + * overridden by this value. + * + * @example [{ url: "https://api.example.com/v1" }] + */ + servers?: Server[]; +} + +/** + * ----- + * Example Object + * ----- + * + * In all cases, the example value is expected to be compatible with the type schema + * of its associated value. Tooling implementations MAY choose to validate compatibility + * automatically, and reject the example value(s) if incompatible. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#example-object | OpenAPI 3.1.1 Example Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#example-object | OpenAPI 3.1.0 Example Object} | + * + * ----- + * Fields + * ----- + * + * @property `summary` - Optional Short description for the example + * @property `description` - Optional Long description for the example + * @property `value` - Optional Embedded literal example + * @property `externalValue` - Optional A URI that points to the literal example + * @property `x-${string}` - Specification Extensions + * + * @note + * The `value` and `externalValue` fields are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (embedded example): + * ```ts + * const example: Example = { + * summary: "A user example", + * value: { + * id: 1, + * name: "John Doe", + * email: "john@example.com" + * } + * }; + * ``` + * + * @example (external example): + * ```ts + * const example: Example = { + * summary: "External user example", + * externalValue: "https://example.com/examples/user-example.json" + * }; + * ``` + */ +export interface Example extends Extension { + /** + * Short description for the example. + * + * @example "A user example" + * @example "Error response example" + */ + summary?: string; + + /** + * Long description for the example. CommonMark syntax MAY be used for rich text representation. + * + * @example "This example shows a typical user object with all required fields" + * @example "This example demonstrates an error response when validation fails" + */ + description?: string; + + /** + * Embedded literal example. The value field and externalValue field are mutually exclusive. + * To represent examples of media types that cannot naturally represented in JSON or YAML, + * use a string value to contain the example, escaping where necessary. + * + * @example { id: 1, name: "John Doe" } + * @example "example string" + * @example 42 + */ + value?: unknown; + + /** + * A URI that points to the literal example. This provides the capability to reference + * examples that cannot easily be included in JSON or YAML documents. The value field + * and externalValue field are mutually exclusive. + * + * @example "https://example.com/examples/user-example.json" + * @example "https://example.com/examples/error-example.xml" + */ + externalValue?: string; +} + +/** + * ----- + * Parameter Object + * ----- + * + * Describes a single operation parameter. A unique parameter is defined by a combination + * of a name and location. The parameter name is case sensitive. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#parameter-object | OpenAPI 3.1.1 Parameter Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#parameter-object | OpenAPI 3.1.0 Parameter Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The name of the parameter + * @property `in` - Required The location of the parameter + * @property `description` - Optional A brief description of the parameter + * @property `required` - Optional Determines whether this parameter is mandatory + * @property `deprecated` - Optional Specifies that a parameter is deprecated + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters + * @property `style` - Optional Describes how the parameter value will be serialized + * @property `explode` - Optional When this is true, parameter values of type array or object generate separate parameters for each value + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * @property `schema` - Optional The schema defining the type used for the parameter + * @property `example` - Optional Example of the parameter's potential value + * @property `examples` - Optional Examples of the parameter's potential value + * @property `content` - Optional A map containing the representations for the parameter + * @property `x-${string}` - Specification Extensions + * + * @note + * The `schema` and `content` fields are mutually exclusive. For path parameters, `required` must be true. + * + * ----- + * Examples + * ----- + * + * @example (query parameter): + * ```ts + * const parameter: Parameter = { + * name: "limit", + * in: "query", + * description: "Maximum number of items to return", + * required: false, + * schema: { type: "integer", minimum: 1, maximum: 100 } + * }; + * ``` + * + * @example (path parameter): + * ```ts + * const parameter: Parameter = { + * name: "userId", + * in: "path", + * description: "The user ID", + * required: true, + * schema: { type: "string" } + * }; + * ``` + */ +export interface Parameter extends Extension { + /** + * The name of the parameter. Parameter names are case sensitive. + * + * @example "userId" + * @example "limit" + * @example "X-API-Key" + */ + name: string; + + /** + * The location of the parameter. Possible values are "query", "header", "path" or "cookie". + * + * @example "query" + * @example "path" + * @example "header" + * @example "cookie" + */ + in: "query" | "header" | "path" | "cookie"; + + /** + * A brief description of the parameter. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * + * @example "The user ID to retrieve" + * @example "Maximum number of items to return" + */ + description?: string; + + /** + * Determines whether this parameter is mandatory. If the parameter location is "path", + * this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be + * included and its default value is false. + * + * @example true + * @example false + */ + required?: boolean; + + /** + * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. + * Default value is false. + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * Sets the ability to pass empty-valued parameters. This is valid only for query + * parameters and allows sending a parameter with an empty value. Default value is false. + * + * @example true + * @example false + */ + allowEmptyValue?: boolean; + + /** + * Describes how the parameter value will be serialized depending on the type of the + * parameter value. Default values (based on value of in): for query - form; for path - simple; + * for header - simple; for cookie - form. + * + * @example "simple" + * @example "form" + * @example "matrix" + * @example "label" + * @example "spaceDelimited" + * @example "pipeDelimited" + * @example "deepObject" + */ + style?: string; + + /** + * When this is true, parameter values of type array or object generate separate parameters + * for each value of the array or key-value pair of the map. For other types of parameters + * this property has no effect. When style is form, the default value is true. For all other + * styles, the default value is false. + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the parameter value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only + * applies to parameters with an in value of query. The default value is false. + * + * @example true + * @example false + */ + allowReserved?: boolean; + + /** + * The schema defining the type used for the parameter. This field is mutually exclusive + * with the content field. + * + * @example { type: "string" } + * @example { type: "integer", minimum: 1 } + */ + schema?: Schema; + + /** + * Example of the parameter's potential value. The example SHOULD match the specified + * schema and encoding properties if present. The example field is mutually exclusive + * of the examples field. Furthermore, if referencing a schema that contains an example, + * the example value SHALL override the example provided by the schema. + * + * @example "example value" + * @example 42 + * @example { id: 1, name: "John" } + */ + example?: unknown; + + /** + * Examples of the parameter's potential value. Each example SHOULD contain a value in + * the correct format as specified in the parameter encoding. The examples field is + * mutually exclusive of the example field. Furthermore, if referencing a schema that + * contains an example, the examples value SHALL override the example provided by the schema. + * + * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } } + */ + examples?: Record; + + /** + * A map containing the representations for the parameter. The key is the media type + * and the value describes it. The map MUST only contain one entry. This field is + * mutually exclusive with the schema field. + * + * @example { "application/json": { schema: { type: "string" } } } + */ + content?: Record; +} + +/** + * ----- + * Request Body Object + * ----- + * + * Describes a single request body. A request body is the payload sent with an HTTP request. + * The request body is only supported in HTTP methods where the HTTP 1.1 specification + * RFC7231 has explicitly defined semantics for request bodies. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#request-body-object | OpenAPI 3.1.1 Request Body Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#request-body-object | OpenAPI 3.1.0 Request Body Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A brief description of the request body + * @property `content` - Required The content of the request body + * @property `required` - Optional Determines if the request body is required in the request + * @property `x-${string}` - Specification Extensions + * + * @note + * The `content` field is required and must contain at least one media type. + * + * ----- + * Examples + * ----- + * + * @example (JSON request body): + * ```ts + * const requestBody: RequestBody = { + * description: "User data to create", + * required: true, + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/User" } + * } + * } + * }; + * ``` + * + * @example (multipart request body): + * ```ts + * const requestBody: RequestBody = { + * description: "File upload", + * content: { + * "multipart/form-data": { + * schema: { + * type: "object", + * properties: { + * file: { type: "string", format: "binary" } + * } + * } + * } + * } + * }; + * ``` + */ +export interface RequestBody extends Extension { + /** + * A brief description of the request body. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * + * @example "User data to create" + * @example "File upload with metadata" + */ + description?: string; + + /** + * The content of the request body. The key is a media type or media type range and + * the value describes it. For request bodies that are sent using multipart/form-data, + * the encoding property is used to describe the encoding of the request body. + * + * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } + * @example { "multipart/form-data": { schema: { type: "object", properties: { file: { type: "string", format: "binary" } } } } } + */ + content: Record; + + /** + * Determines if the request body is required in the request. Defaults to false. + * + * @example true + * @example false + */ + required?: boolean; +} + +/** + * ----- + * Response Object + * ----- + * + * Describes a single response from an API Operation, including design-time, static links + * to operations based on the response. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#response-object | OpenAPI 3.1.1 Response Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#response-object | OpenAPI 3.1.0 Response Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Required A short description of the response + * @property `headers` - Optional Maps a header name to its definition + * @property `content` - Optional A map containing descriptions of potential response payloads + * @property `links` - Optional A map of operations links that can be followed from the response + * @property `x-${string}` - Specification Extensions + * + * @note + * The `description` field is required and should describe the response. + * + * ----- + * Examples + * ----- + * + * @example (basic response): + * ```ts + * const response: Response = { + * description: "A list of users", + * content: { + * "application/json": { + * schema: { type: "array", items: { $ref: "#/components/schemas/User" } } + * } + * } + * }; + * ``` + * + * @example (response with headers): + * ```ts + * const response: Response = { + * description: "User created successfully", + * headers: { + * "Location": { + * description: "URL of the created user", + * schema: { type: "string" } + * } + * }, + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/User" } + * } + * } + * }; + * ``` + */ +export interface Response extends Extension { + /** + * A short description of the response. CommonMark syntax MAY be used for rich text representation. + * This field is required. + * + * @example "A list of users" + * @example "User created successfully" + * @example "Bad request - validation failed" + */ + description: string; + + /** + * Maps a header name to its definition. RFC7230 states header names are case insensitive. + * If a response header is defined with the name "Content-Type", it SHALL be ignored. + * + * @example { "X-RateLimit-Limit": { description: "Rate limit per hour", schema: { type: "integer" } } } + */ + headers?: Record; + + /** + * A map containing descriptions of potential response payloads. The key is a media type + * or media type range and the value describes it. For responses that match multiple keys, + * only the most specific key is applicable. e.g. text/plain overrides text/* + * + * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } + * @example { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/User" } } } } + */ + content?: Record; + + /** + * A map of operations links that can be followed from the response. The key of the map + * is a short name for the link, following the naming constraints of the names for + * Component Objects. + * + * @example { "GetUser": { operationId: "getUserById", parameters: { userId: "$response.body#/id" } } } + */ + links?: Record; +} + +/** + * ----- + * Header Object + * ----- + * + * The Header Object follows the structure of the Parameter Object with the following changes: + * 1. `name` MUST NOT be specified, it is given in the corresponding headers map. + * 2. `in` MUST NOT be specified, it is implicitly in header. + * 3. All traits that are affected by the location MUST be applicable to a location of header + * (for example, style). + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#header-object | OpenAPI 3.1.1 Header Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#header-object | OpenAPI 3.1.0 Header Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A brief description of the header + * @property `required` - Optional Determines whether this header is mandatory + * @property `deprecated` - Optional Specifies that a header is deprecated + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued headers + * @property `style` - Optional Describes how the header value will be serialized + * @property `explode` - Optional When this is true, header values of type array or object generate separate headers for each value + * @property `allowReserved` - Optional Determines whether the header value SHOULD allow reserved characters + * @property `schema` - Optional The schema defining the type used for the header + * @property `example` - Optional Example of the header's potential value + * @property `examples` - Optional Examples of the header's potential value + * @property `content` - Optional A map containing the representations for the header + * @property `x-${string}` - Specification Extensions + * + * @note + * The `schema` and `content` fields are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (simple header): + * ```ts + * const header: Header = { + * description: "Rate limit per hour", + * required: false, + * schema: { type: "integer" } + * }; + * ``` + * + * @example (header with content): + * ```ts + * const header: Header = { + * description: "Custom header with JSON content", + * content: { + * "application/json": { + * schema: { type: "object", properties: { value: { type: "string" } } } + * } + * } + * }; + * ``` + */ +export interface Header extends Extension { + /** + * A brief description of the header. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * + * @example "Rate limit per hour" + * @example "Custom authentication token" + */ + description?: string; + + /** + * Determines whether this header is mandatory. The property MAY be included and its + * default value is false. + * + * @example true + * @example false + */ + required?: boolean; + + /** + * Specifies that a header is deprecated and SHOULD be transitioned out of usage. + * Default value is false. + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * Sets the ability to pass empty-valued headers. This is valid only for headers + * and allows sending a header with an empty value. Default value is false. + * + * @example true + * @example false + */ + allowEmptyValue?: boolean; + + /** + * Describes how the header value will be serialized. The default value is "simple". + * + * @example "simple" + * @example "form" + */ + style?: string; + + /** + * When this is true, header values of type array or object generate separate headers + * for each value of the array or key-value pair of the map. For other types of headers + * this property has no effect. When style is form, the default value is true. For all other + * styles, the default value is false. + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the header value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. + * + * @example true + * @example false + */ + allowReserved?: boolean; + + /** + * The schema defining the type used for the header. This field is mutually exclusive + * with the content field. + * + * @example { type: "string" } + * @example { type: "integer", minimum: 0 } + */ + schema?: Schema; + + /** + * Example of the header's potential value. The example SHOULD match the specified + * schema and encoding properties if present. The example field is mutually exclusive + * of the examples field. + * + * @example "example value" + * @example 42 + */ + example?: unknown; + + /** + * Examples of the header's potential value. Each example SHOULD contain a value in + * the correct format as specified in the header encoding. The examples field is + * mutually exclusive of the example field. + * + * @example { "header1": { summary: "A header example", value: "example value" } } + */ + examples?: Record; + + /** + * A map containing the representations for the header. The key is the media type + * and the value describes it. The map MUST only contain one entry. This field is + * mutually exclusive with the schema field. + * + * @example { "application/json": { schema: { type: "string" } } } + */ + content?: Record; +} + +/** + * ----- + * Media Type Object + * ----- + * + * Each Media Type Object provides schema and examples for the media type identified by its key. + * Media Type Objects can be used in a Content Object. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#media-type-object | OpenAPI 3.1.1 Media Type Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#media-type-object | OpenAPI 3.1.0 Media Type Object} | + * + * ----- + * Fields + * ----- + * + * @property `schema` - Optional The schema defining the content of the request, response, or parameter + * @property `example` - Optional Example of the media type + * @property `examples` - Optional Examples of the media type + * @property `encoding` - Optional A map between a property name and its encoding information + * @property `x-${string}` - Specification Extensions + * + * @note + * The `example` and `examples` fields are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (JSON media type): + * ```ts + * const mediaType: MediaType = { + * schema: { $ref: "#/components/schemas/User" }, + * example: { id: 1, name: "John Doe" } + * }; + * ``` + * + * @example (multipart media type with encoding): + * ```ts + * const mediaType: MediaType = { + * schema: { + * type: "object", + * properties: { + * file: { type: "string", format: "binary" }, + * description: { type: "string" } + * } + * }, + * encoding: { + * file: { contentType: "image/png" }, + * description: { contentType: "text/plain" } + * } + * }; + * ``` + */ +export interface MediaType extends Extension { + /** + * The schema defining the content of the request, response, or parameter. + * + * @example { $ref: "#/components/schemas/User" } + * @example { type: "array", items: { type: "string" } } + */ + schema?: Schema; + + /** + * Example of the media type. The example SHOULD match the specified schema and encoding + * properties if present. The example field is mutually exclusive of the examples field. + * Furthermore, if referencing a schema that contains an example, the example value + * SHALL override the example provided by the schema. + * + * @example { id: 1, name: "John Doe" } + * @example "example string" + * @example 42 + */ + example?: unknown; + + /** + * Examples of the media type. Each example SHOULD contain a value in the correct format + * as specified in the media type encoding. The examples field is mutually exclusive + * of the example field. Furthermore, if referencing a schema that contains an example, + * the examples value SHALL override the example provided by the schema. + * + * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } } + */ + examples?: Record; + + /** + * A map between a property name and its encoding information. The key, being the property + * name, MUST exist in the schema as a property. The encoding object SHALL only apply to + * requestBody objects when the media type is multipart or application/x-www-form-urlencoded. + * + * @example { "file": { contentType: "image/png" }, "description": { contentType: "text/plain" } } + */ + encoding?: Record; +} + +/** + * ----- + * Encoding Object + * ----- + * + * A single encoding definition applied to a single schema property. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#encoding-object | OpenAPI 3.1.1 Encoding Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#encoding-object | OpenAPI 3.1.0 Encoding Object} | + * + * ----- + * Fields + * ----- + * + * @property `contentType` - Optional The Content-Type for encoding a specific property + * @property `headers` - Optional A map allowing additional information to be provided as headers + * @property `style` - Optional Describes how a specific property value will be serialized + * @property `explode` - Optional When this is true, property values of type array or object generate separate parameters for each value + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * @property `x-${string}` - Specification Extensions + * + * @note + * The `style` property only applies to form data and query parameters. + * + * ----- + * Examples + * ----- + * + * @example (basic encoding): + * ```ts + * const encoding: Encoding = { + * contentType: "image/png", + * style: "form" + * }; + * ``` + * + * @example (encoding with headers): + * ```ts + * const encoding: Encoding = { + * contentType: "application/json", + * headers: { + * "X-Custom-Header": { + * description: "Custom header for this encoding", + * schema: { type: "string" } + * } + * } + * }; + * ``` + */ +export interface Encoding extends Extension { + /** + * The Content-Type for encoding a specific property. Default value depends on the + * property type: for string with format being binary – application/octet-stream; + * for other primitive types – text/plain; for object – application/json; + * for array – the default is determined based on the inner type. + * + * @example "image/png" + * @example "application/json" + * @example "text/plain" + */ + contentType?: string; + + /** + * A map allowing additional information to be provided as headers, for example + * Content-Disposition. Content-Type is described separately and SHALL be ignored + * in this section. This property SHALL be ignored if the request body media type + * is not a multipart. + * + * @example { "Content-Disposition": { description: "File attachment", schema: { type: "string" } } } + */ + headers?: Record; + + /** + * Describes how a specific property value will be serialized depending on its type. + * See Parameter Object for details on the style property. The behavior follows the + * same values as query parameters, including default values. This property SHALL be + * ignored if the request body media type is not application/x-www-form-urlencoded + * or multipart/form-data. + * + * @example "form" + * @example "spaceDelimited" + * @example "pipeDelimited" + * @example "deepObject" + */ + style?: string; + + /** + * When this is true, property values of type array or object generate separate + * parameters for each value of the array or key-value pair of the map. For other + * types of properties this property has no effect. When style is form, the default + * value is true. For all other styles, the default value is false. This property + * SHALL be ignored if the request body media type is not application/x-www-form-urlencoded + * or multipart/form-data. + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the parameter value SHOULD allow reserved characters, as defined + * by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default + * value is false. This property SHALL be ignored if the request body media type is + * not application/x-www-form-urlencoded. + * + * @example true + * @example false + */ + allowReserved?: boolean; +} + +/** + * ----- + * Link Object + * ----- + * + * The Link object represents a possible design-time link for a response. The presence of a link + * does not guarantee the caller's ability to successfully invoke it, rather it provides a known + * relationship and traversal mechanism between responses and other operations. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#link-object | OpenAPI 3.1.1 Link Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#link-object | OpenAPI 3.1.0 Link Object} | + * + * ----- + * Fields + * ----- + * + * @property `operationRef` - Optional A relative or absolute reference to an OAS operation + * @property `operationId` - Optional The name of an existing, resolvable OAS operation + * @property `parameters` - Optional A map representing parameters to pass to an operation + * @property `requestBody` - Optional A literal value or expression to use as a request body + * @property `description` - Optional A description of the link + * @property `server` - Optional A server object to be used by the target operation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `operationRef` and `operationId` fields are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (link with operationId): + * ```ts + * const link: Link = { + * operationId: "getUserById", + * parameters: { + * userId: "$response.body#/id" + * }, + * description: "Get the user by ID" + * }; + * ``` + * + * @example (link with operationRef): + * ```ts + * const link: Link = { + * operationRef: "#/paths/~1users~1{userId}/get", + * parameters: { + * userId: "$response.body#/id" + * } + * }; + * ``` + */ +export interface Link extends Extension { + /** + * A relative or absolute reference to an OAS operation. This field is mutually exclusive + * of the operationId field, and MUST point to an Operation Object. Relative operationRef + * values MAY be used to locate an existing Operation Object in the OpenAPI definition. + * + * @example "#/paths/~1users~1{userId}/get" + * @example "https://example.com/openapi.json#/paths/~1users~1{userId}/get" + */ + operationRef?: string; + + /** + * The name of an existing, resolvable OAS operation, as defined with a unique operationId. + * This field is mutually exclusive of the operationRef field. + * + * @example "getUserById" + * @example "createUser" + */ + operationId?: string; + + /** + * A map representing parameters to pass to an operation as specified with operationId + * or identified via operationRef. The key is the parameter name to be used, whereas + * the value can be a constant or an expression to be evaluated and passed to the linked + * operation. The parameter name can be qualified using the parameter location [{in}.]{name} + * for operations that use the same parameter name in different locations (e.g. path.id). + * + * @example { "userId": "$response.body#/id" } + * @example { "path.id": "$response.body#/id", "query.limit": 10 } + */ + parameters?: Record; + + /** + * A literal value or expression to use as a request body when calling the target operation. + * + * @example { "name": "John Doe", "email": "john@example.com" } + * @example "$request.body" + */ + requestBody?: unknown; + + /** + * A description of the link. CommonMark syntax MAY be used for rich text representation. + * + * @example "Get the user by ID" + * @example "Create a new user with the provided data" + */ + description?: string; + + /** + * A server object to be used by the target operation. + * + * @example { url: "https://api.example.com/v1" } + */ + server?: Server; +} + +/** + * ----- + * Callback Object + * ----- + * + * A map of possible out-of band callbacks related to the parent operation. Each value in the map + * is a Path Item Object that describes a set of requests that may be initiated by the API provider + * and the expected responses. The key value used to identify the callback object is an expression, + * evaluated at runtime, that identifies a URL to use for the callback operation. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#callback-object | OpenAPI 3.1.1 Callback Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#callback-object | OpenAPI 3.1.0 Callback Object} | + * + * ----- + * Fields + * ----- + * + * @property `{expression}` - A Path Item Object or Reference to a Path Item Object + * + * @note + * The key is a runtime expression that identifies a URL to use for the callback operation. + * The expression is evaluated at runtime and MUST resolve to a URL. + * + * ----- + * Examples + * ----- + * + * @example (simple callback): + * ```ts + * const callback: Callback = { + * "{$request.body#/callbackUrl}": { + * post: { + * requestBody: { + * description: "Callback payload", + * content: { + * "application/json": { + * schema: { $ref: "#/components/schemas/CallbackPayload" } + * } + * } + * }, + * responses: { + * "200": { + * description: "Callback received successfully" + * } + * } + * } + * } + * }; + * ``` + * + * @example (callback with multiple operations): + * ```ts + * const callback: Callback = { + * "{$request.body#/callbackUrl}": { + * post: { + * summary: "Success callback", + * requestBody: { description: "Success payload" } + * }, + * put: { + * summary: "Update callback", + * requestBody: { description: "Update payload" } + * } + * } + * }; + * ``` + */ +export interface Callback { + /** + * A runtime expression that identifies a URL to use for the callback operation. + * The expression is evaluated at runtime and MUST resolve to a URL. The value + * is a Path Item Object that describes the callback operations. + * + * @example "{$request.body#/callbackUrl}" + * @example "{$request.body#/webhookUrl}" + * @example "{$request.body#/notificationUrl}" + */ + [expression: string]: PathItemObject | Reference; +} diff --git a/3.1.x/references.ts b/3.1/references.ts similarity index 55% rename from 3.1.x/references.ts rename to 3.1/references.ts index e65569b..aa4c131 100644 --- a/3.1.x/references.ts +++ b/3.1/references.ts @@ -20,10 +20,10 @@ * Fields * ----- * - * @key `$ref` - Required The reference string - * @key `description` - Optional A description of the referenced object - * @key `summary` - Optional A short summary of the referenced object - * @key `x-${string}` - Specification Extensions + * @property `$ref` - Required The reference string + * @property `description` - Optional A description of the referenced object + * @property `summary` - Optional A short summary of the referenced object + * @property `x-${string}` - Specification Extensions * * @note * The `$ref` field is required and must be a valid JSON Reference. @@ -55,31 +55,31 @@ * ``` */ export interface Reference { - /** - * The reference string. This field is required and must be a valid JSON Reference. - * It can reference internal components using `#/` or external resources using URLs. - * - * @example "#/components/schemas/User" - * @example "#/components/responses/NotFound" - * @example "https://example.com/schemas/User.json" - */ - $ref: string + /** + * The reference string. This field is required and must be a valid JSON Reference. + * It can reference internal components using `#/` or external resources using URLs. + * + * @example "#/components/schemas/User" + * @example "#/components/responses/NotFound" + * @example "https://example.com/schemas/User.json" + */ + $ref: string; - /** - * A description of the referenced object. This can be used to provide - * additional context about what the referenced object represents. - * - * @example "A user object containing user information" - * @example "Standard error response for not found resources" - */ - description?: string + /** + * A description of the referenced object. This can be used to provide + * additional context about what the referenced object represents. + * + * @example "A user object containing user information" + * @example "Standard error response for not found resources" + */ + description?: string; - /** - * A short summary of the referenced object. This can be used to provide - * a brief overview of what the referenced object represents. - * - * @example "User schema" - * @example "Not found response" - */ - summary?: string + /** + * A short summary of the referenced object. This can be used to provide + * a brief overview of what the referenced object represents. + * + * @example "User schema" + * @example "Not found response" + */ + summary?: string; } diff --git a/3.1/schema.ts b/3.1/schema.ts new file mode 100644 index 0000000..7dcec7c --- /dev/null +++ b/3.1/schema.ts @@ -0,0 +1,254 @@ +import type { + ArraySchema, + BooleanSchema, + CompositionSchema, + IntegerSchema, + NullSchema, + NumberSchema, + ObjectSchema, + ReferenceSchema, + StringSchema, +} from "./data-types"; +import type { Extension } from "./extensions"; + +/** + * ----- + * Discriminator Object + * ----- + * + * The Discriminator Object is used to aid in serialization, deserialization, and validation. + * It can be used to differentiate between other schemas which may satisfy the payload description. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#discriminator-object | OpenAPI 3.1.1 Discriminator Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#discriminator-object | OpenAPI 3.1.0 Discriminator Object} | + * + * ----- + * Fields + * ----- + * + * @property `propertyName` - Required The name of the property in the payload that will hold the discriminator value + * @property `mapping` - Optional An object to hold mappings between payload values and schema names or references + * @property `x-${string}` - Specification Extensions + * + * @note + * The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. + * + * ----- + * Examples + * ----- + * + * @example (basic discriminator): + * ```ts + * const discriminator: Discriminator = { + * propertyName: "petType" + * }; + * ``` + * + * @example (discriminator with mapping): + * ```ts + * const discriminator: Discriminator = { + * propertyName: "petType", + * mapping: { + * dog: "#/components/schemas/Dog", + * cat: "#/components/schemas/Cat" + * } + * }; + * ``` + */ +export interface Discriminator extends Extension { + /** + * The name of the property in the payload that will hold the discriminator value. + * This property must be present in the payload. + * + * Example: `"petType"` + */ + propertyName: string; + + /** + * An object to hold mappings between payload values and schema names or references. + * If not provided, the schema name will be used as the discriminator value. + * + * Example: `{ dog: "#/components/schemas/Dog", cat: "#/components/schemas/Cat" }` + */ + mapping?: Record; +} + +/** + * ----- + * Schema Object + * ----- + * + * The Schema Object allows the definition of input and output data types. These types + * can be objects, but also primitives and arrays. This object is an extended subset + * of the JSON Schema Specification Draft 2020-12. + * + * The Schema Object is a discriminated union that enforces mutual-exclusion and + * co-occurrence rules as specified in the OpenAPI 3.1.x specification. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#schema-object | OpenAPI 3.1.1 Schema Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#schema-object | OpenAPI 3.1.0 Schema Object} | + * + * ----- + * Schema Types + * ----- + * + * The Schema union includes the following types: + * + * **Reference Schema:** + * @property `$ref` - A reference to a schema (exclusive with other properties) + * @property `description` - A description of the referenced schema + * + * **String Schema:** + * @property `type: "string"` - The type identifier for string schemas + * @property `format` - The format of the string (email, date, uuid, etc.) + * @property `maxLength` - The maximum length of the string + * @property `minLength` - The minimum length of the string + * @property `pattern` - A regular expression pattern the string must match + * @property `enum` - An enumeration of string values + * @property `const` - A constant string value + * + * **Number Schema:** + * @property `type: "number"` - The type identifier for number schemas + * @property `format` - The format of the number (float, double) + * @property `multipleOf` - A number that must be a multiple of this value + * @property `maximum` - The maximum value (inclusive) + * @property `exclusiveMaximum` - The maximum value (exclusive) + * @property `minimum` - The minimum value (inclusive) + * @property `exclusiveMinimum` - The minimum value (exclusive) + * @property `enum` - An enumeration of number values + * @property `const` - A constant number value + * + * **Integer Schema:** + * @property `type: "integer"` - The type identifier for integer schemas + * @property `format` - The format of the integer (int32, int64) + * @property `multipleOf` - An integer that must be a multiple of this value + * @property `maximum` - The maximum value (inclusive) + * @property `exclusiveMaximum` - The maximum value (exclusive) + * @property `minimum` - The minimum value (inclusive) + * @property `exclusiveMinimum` - The minimum value (exclusive) + * @property `enum` - An enumeration of integer values + * @property `const` - A constant integer value + * + * **Boolean Schema:** + * @property `type: "boolean"` - The type identifier for boolean schemas + * @property `enum` - An enumeration of boolean values + * @property `const` - A constant boolean value + * + * **Null Schema:** + * @property `type: "null"` - The type identifier for null schemas + * @property `enum` - An enumeration of null values + * @property `const` - A constant null value + * + * **Array Schema:** + * @property `type: "array"` - The type identifier for array schemas + * @property `items` - The schema for array items + * @property `prefixItems` - The schema for array items at specific positions + * @property `contains` - The schema that array must contain at least one item matching + * @property `minContains` - The minimum number of items that must match contains + * @property `maxContains` - The maximum number of items that must match contains + * @property `minItems` - The minimum number of items in the array + * @property `maxItems` - The maximum number of items in the array + * @property `uniqueItems` - Whether array items must be unique + * + * **Object Schema:** + * @property `type: "object"` - The type identifier for object schemas + * @property `properties` - A map of property names to their schemas + * @property `required` - An array of required property names + * @property `additionalProperties` - The schema for additional properties + * @property `patternProperties` - A map of regex patterns to schemas + * @property `propertyNames` - The schema for property names + * @property `minProperties` - The minimum number of properties + * @property `maxProperties` - The maximum number of properties + * @property `dependentRequired` - A map of property names to arrays of required properties + * @property `dependentSchemas` - A map of property names to schemas + * + * **Composition Schema:** + * @property `allOf` - An array of schemas that must all be satisfied + * @property `anyOf` - An array of schemas where at least one must be satisfied + * @property `oneOf` - An array of schemas where exactly one must be satisfied + * @property `not` - A schema that must not be satisfied + * @property `if` - A schema for conditional validation + * @property `then` - A schema to apply if if condition is met + * @property `else` - A schema to apply if if condition is not met + * + * **Common Properties:** + * @property `title` - A short title for the schema + * @property `description` - A description of the schema + * @property `default` - The default value for the schema + * @property `examples` - An array of example values + * @property `enum` - An enumeration of allowed values + * @property `const` - A constant allowed value + * @property `discriminator` - A discriminator object for polymorphism + * @property `xml` - XML-specific metadata + * @property `externalDocs` - External documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The Schema Object is a discriminated union that enforces mutual-exclusion and + * co-occurrence rules. When `$ref` is present, no other properties except + * `description` and extensions are allowed. Composition keywords are mutually + * exclusive with `$ref`. + * + * ----- + * Examples + * ----- + * + * @example (reference schema): + * ```ts + * const schema: Schema = { + * $ref: "#/components/schemas/User" + * }; + * ``` + * + * @example (string schema): + * ```ts + * const schema: Schema = { + * type: "string", + * format: "email", + * maxLength: 255 + * }; + * ``` + * + * @example (object schema): + * ```ts + * const schema: Schema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * }, + * required: ["name"] + * }; + * ``` + * + * @example (null schema): + * ```ts + * const schema: Schema = { + * type: "null" + * }; + * ``` + * + * @example (composition schema): + * ```ts + * const schema: Schema = { + * allOf: [ + * { type: "object", properties: { name: { type: "string" } } }, + * { type: "object", properties: { age: { type: "number" } } } + * ] + * }; + * ``` + */ +export type Schema = + | ReferenceSchema + | StringSchema + | NumberSchema + | IntegerSchema + | BooleanSchema + | ArraySchema + | ObjectSchema + | NullSchema + | CompositionSchema; diff --git a/3.1/security.ts b/3.1/security.ts new file mode 100644 index 0000000..58fc389 --- /dev/null +++ b/3.1/security.ts @@ -0,0 +1,366 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Security Scheme Object + * ----- + * + * Defines a security scheme that can be used by the operations. Supported schemes + * are HTTP authentication, an API key (either as a header, a cookie parameter or + * as a query parameter), mutual TLS (use of a client certificate), OAuth2's common + * flows (implicit, password, client credentials and authorization code) as defined + * in RFC6749, and OpenID Connect Discovery. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#security-scheme-object | OpenAPI 3.1.1 Security Scheme Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#security-scheme-object | OpenAPI 3.1.0 Security Scheme Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Required The type of the security scheme + * @property `description` - Optional A short description for security scheme + * @property `name` - Optional The name of the header, query or cookie parameter to be used + * @property `in` - Optional The location of the API key + * @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header + * @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted + * @property `flows` - Optional An object containing configuration information for the flow types supported + * @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values + * @property `x-${string}` - Specification Extensions + * + * @note + * The `type` field is required. Other fields depend on the security scheme type. + * + * ----- + * Examples + * ----- + * + * @example (API Key): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "apiKey", + * name: "X-API-Key", + * in: "header" + * }; + * ``` + * + * @example (HTTP Basic): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "http", + * scheme: "basic" + * }; + * ``` + * + * @example (OAuth2): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "oauth2", + * flows: { + * authorizationCode: { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read:pets": "read your pets", + * "write:pets": "modify pets in your account" + * } + * } + * } + * }; + * ``` + * + * @example (Mutual TLS): + * ```ts + * const securityScheme: SecurityScheme = { + * type: "mutualTLS" + * }; + * ``` + */ +export interface SecurityScheme extends Extension { + /** + * The type of the security scheme. This field is required. + * + * @example "apiKey" + * @example "http" + * @example "mutualTLS" + * @example "oauth2" + * @example "openIdConnect" + */ + type: "apiKey" | "http" | "mutualTLS" | "oauth2" | "openIdConnect"; + + /** + * A short description for security scheme. CommonMark syntax MAY be used + * for rich text representation. + * + * @example "API key authentication" + * @example "OAuth2 authentication with authorization code flow" + */ + description?: string; + + /** + * The name of the header, query or cookie parameter to be used. This field + * is required for `apiKey` type. + * + * @example "X-API-Key" + * @example "api_key" + * @example "sessionId" + */ + name?: string; + + /** + * The location of the API key. This field is required for `apiKey` type. + * + * @example "header" + * @example "query" + * @example "cookie" + */ + in?: "query" | "header" | "cookie"; + + /** + * The name of the HTTP Authorization scheme to be used in the Authorization + * header. This field is required for `http` type. + * + * @example "basic" + * @example "bearer" + * @example "digest" + */ + scheme?: string; + + /** + * A hint to the client to identify how the bearer token is formatted. Bearer + * tokens are usually generated by an authorization server, so this information + * is primarily for documentation purposes. + * + * @example "JWT" + * @example "Bearer" + */ + bearerFormat?: string; + + /** + * An object containing configuration information for the flow types supported. + * This field is required for `oauth2` type. + * + * @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } } + */ + flows?: OAuthFlows; + + /** + * OpenId Connect URL to discover OAuth2 configuration values. This MUST be + * in the form of a URL. This field is required for `openIdConnect` type. + * + * @example "https://example.com/.well-known/openid_configuration" + */ + openIdConnectUrl?: string; +} + +/** + * ----- + * OAuth Flows Object + * ----- + * + * Allows configuration of the supported OAuth Flows. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flows-object | OpenAPI 3.1.1 OAuth Flows Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flows-object | OpenAPI 3.1.0 OAuth Flows Object} | + * + * ----- + * Fields + * ----- + * + * @property `implicit` - Optional Configuration for the OAuth Implicit flow + * @property `password` - Optional Configuration for the OAuth Resource Owner Password flow + * @property `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow + * @property `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. At least one flow must be specified. + * + * ----- + * Examples + * ----- + * + * @example (authorization code flow): + * ```ts + * const oauthFlows: OAuthFlows = { + * authorizationCode: { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read:pets": "read your pets", + * "write:pets": "modify pets in your account" + * } + * } + * }; + * ``` + */ +export interface OAuthFlows extends Extension { + /** + * Configuration for the OAuth Implicit flow. + * + * @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { "read:pets": "read your pets" } } + */ + implicit?: OAuthFlow; + + /** + * Configuration for the OAuth Resource Owner Password flow. + * + * @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } } + */ + password?: OAuthFlow; + + /** + * Configuration for the OAuth Client Credentials flow. + * + * @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } } + */ + clientCredentials?: OAuthFlow; + + /** + * Configuration for the OAuth Authorization Code flow. + * + * @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } } + */ + authorizationCode?: OAuthFlow; +} + +/** + * ----- + * OAuth Flow Object + * ----- + * + * Configuration details for a supported OAuth Flow. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flow-object | OpenAPI 3.1.1 OAuth Flow Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flow-object | OpenAPI 3.1.0 OAuth Flow Object} | + * + * ----- + * Fields + * ----- + * + * @property `authorizationUrl` - Optional The authorization URL to be used for this flow + * @property `tokenUrl` - Optional The token URL to be used for this flow + * @property `refreshUrl` - Optional The URL to be used for obtaining refresh tokens + * @property `scopes` - Required The available scopes for the OAuth2 security scheme + * @property `x-${string}` - Specification Extensions + * + * @note + * The `scopes` field is required. Other fields depend on the flow type. + * + * ----- + * Examples + * ----- + * + * @example (authorization code flow): + * ```ts + * const oauthFlow: OAuthFlow = { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read:pets": "read your pets", + * "write:pets": "modify pets in your account" + * } + * }; + * ``` + */ +export interface OAuthFlow extends Extension { + /** + * The authorization URL to be used for this flow. This MUST be in the form of a URL. + * This field is required for `implicit` and `authorizationCode` flows. + * + * @example "https://example.com/oauth/authorize" + */ + authorizationUrl?: string; + + /** + * The token URL to be used for this flow. This MUST be in the form of a URL. + * This field is required for `password`, `clientCredentials`, and `authorizationCode` flows. + * + * @example "https://example.com/oauth/token" + */ + tokenUrl?: string; + + /** + * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. + * + * @example "https://example.com/oauth/refresh" + */ + refreshUrl?: string; + + /** + * The available scopes for the OAuth2 security scheme. A map between the scope + * name and a short description for it. This field is required. + * + * @example { "read:pets": "read your pets", "write:pets": "modify pets in your account" } + */ + scopes: Record; +} + +/** + * ----- + * Security Requirement Object + * ----- + * + * Lists the required security schemes for execution of the operation. The name + * used for each property MUST correspond to a security scheme declared in the + * Security Schemes under the Components Object. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#security-requirement-object | OpenAPI 3.1.1 Security Requirement Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#security-requirement-object | OpenAPI 3.1.0 Security Requirement Object} | + * + * ----- + * Fields + * ----- + * + * @property `{name}` - Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object + * + * @note + * The property names correspond to security scheme names. The values are arrays of scope names. + * + * ----- + * Examples + * ----- + * + * @example (API key): + * ```ts + * const securityRequirement: SecurityRequirement = { + * "api_key": [] + * }; + * ``` + * + * @example (OAuth2): + * ```ts + * const securityRequirement: SecurityRequirement = { + * "petstore_auth": ["write:pets", "read:pets"] + * }; + * ``` + * + * @example (multiple schemes): + * ```ts + * const securityRequirement: SecurityRequirement = { + * "api_key": [], + * "petstore_auth": ["write:pets", "read:pets"] + * }; + * ``` + */ +export interface SecurityRequirement { + /** + * Each name MUST correspond to a security scheme which is declared in the + * Security Schemes under the Components Object. The value is an array of + * scope names required for the execution. For OAuth2, the scopes are the + * scopes required for the execution. For other security schemes, the array + * MUST be empty. + * + * @example [] + * @example ["write:pets", "read:pets"] + */ + [name: string]: string[]; +} diff --git a/3.1/servers.ts b/3.1/servers.ts new file mode 100644 index 0000000..2ccff94 --- /dev/null +++ b/3.1/servers.ts @@ -0,0 +1,164 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Server Object + * ----- + * + * An object representing a Server. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#server-object | OpenAPI 3.1.1 Server Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#server-object | OpenAPI 3.1.0 Server Object} | + * + * ----- + * Fields + * ----- + * + * @property `url` - Required A URL to the target host + * @property `description` - Optional An optional string describing the host designated by the URL + * @property `variables` - Optional A map between a variable name and its value + * @property `x-${string}` - Specification Extensions + * + * @note + * The `url` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple server): + * ```ts + * const server: Server = { + * url: "https://api.example.com/v1" + * }; + * ``` + * + * @example (server with variables): + * ```ts + * const server: Server = { + * url: "https://{username}.gigantic-server.com:{port}/{basePath}", + * description: "The production API server", + * variables: { + * username: { + * default: "demo", + * description: "this value is assigned by the service provider" + * }, + * port: { + * enum: ["8443", "443"], + * default: "8443" + * }, + * basePath: { + * default: "v2" + * } + * } + * }; + * ``` + */ +export interface Server extends Extension { + /** + * A URL to the target host. This URL supports Server Variables and MAY be relative, + * to indicate that the host location is relative to the location where the OpenAPI + * document is being served. Variable substitutions will be made when a variable + * is named in `{brackets}`. + * + * @example "https://api.example.com/v1" + * @example "https://{username}.gigantic-server.com:{port}/{basePath}" + * @example "/v1" + */ + url: string; + + /** + * An optional string describing the host designated by the URL. CommonMark syntax + * MAY be used for rich text representation. + * + * @example "The production API server" + * @example "The staging API server" + */ + description?: string; + + /** + * A map between a variable name and its value. The value is used for substitution + * in the server's URL template. + * + * @example { username: { default: "demo" }, port: { default: "8443" } } + */ + variables?: Record; +} + +/** + * ----- + * Server Variable Object + * ----- + * + * An object representing a Server Variable for server URL template substitution. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#server-variable-object | OpenAPI 3.1.1 Server Variable Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#server-variable-object | OpenAPI 3.1.0 Server Variable Object} | + * + * ----- + * Fields + * ----- + * + * @property `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set + * @property `default` - Required The default value to use for substitution + * @property `description` - Optional An optional description for the server variable + * @property `x-${string}` - Specification Extensions + * + * @note + * The `default` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple variable): + * ```ts + * const variable: ServerVariable = { + * default: "demo" + * }; + * ``` + * + * @example (variable with enum): + * ```ts + * const variable: ServerVariable = { + * enum: ["8443", "443"], + * default: "8443", + * description: "The port number" + * }; + * ``` + */ +export interface ServerVariable extends Extension { + /** + * An enumeration of string values to be used if the substitution options are + * from a limited set. The array SHOULD NOT be empty. + * + * @example ["8443", "443"] + * @example ["v1", "v2", "v3"] + */ + enum?: string[]; + + /** + * The default value to use for substitution, which SHALL be sent if an alternate + * value is not supplied. Note this behavior is different than the Schema Object's + * treatment of default values, because in those cases parameter values are optional. + * If the enum is defined, the value SHOULD exist in the enum's values. + * + * @example "demo" + * @example "8443" + * @example "v1" + */ + default: string; + + /** + * An optional description for the server variable. CommonMark syntax MAY be used + * for rich text representation. + * + * @example "this value is assigned by the service provider" + * @example "The port number" + */ + description?: string; +} diff --git a/3.1/spec.ts b/3.1/spec.ts new file mode 100644 index 0000000..f9921eb --- /dev/null +++ b/3.1/spec.ts @@ -0,0 +1,209 @@ +import type { Components } from "./components"; +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +import type { Info } from "./info"; +import type { Paths } from "./paths"; +import type { SecurityRequirement } from "./security"; +import type { Server } from "./servers"; +import type { Tag } from "./tags"; +import type { Webhooks } from "./webhooks"; + +/** + * ----- + * OpenAPI Specification + * ----- + * + * This is the root object of the OpenAPI document. It contains all the information + * needed to describe an API, including metadata, servers, paths, components, and more. + * + * The OpenAPI Specification (OAS) defines a standard, language-agnostic interface + * to RESTful APIs which allows both humans and computers to discover and understand + * the capabilities of the service without access to source code, documentation, or + * through network traffic inspection. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#openapi-object | OpenAPI 3.1.1 OpenAPI Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#openapi-object | OpenAPI 3.1.0 OpenAPI Object} | + * + * ----- + * Fields + * ----- + * + * @property `openapi` - Required The version number of the OpenAPI Specification + * @property `info` - Required Provides metadata about the API + * @property `jsonSchemaDialect` - Optional The default value for the $schema keyword within Schema Objects + * @property `servers` - Optional An array of Server Objects + * @property `paths` - Optional The available paths and operations for the API + * @property `webhooks` - Optional The incoming webhooks that MAY be received as part of this API + * @property `components` - Optional An element to hold various schemas for the document + * @property `security` - Optional A declaration of which security mechanisms can be used across the API + * @property `tags` - Optional A list of tags used by the document with additional metadata + * @property `externalDocs` - Optional Additional external documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `openapi` and `info` fields are required. + * + * ----- + * Examples + * ----- + * + * @example (minimal specification): + * ```ts + * const spec: Specification = { + * openapi: "3.1.0", + * info: { + * title: "Pet Store API", + * version: "1.0.0" + * } + * }; + * ``` + * + * @example (complete specification): + * ```ts + * const spec: Specification = { + * openapi: "3.1.0", + * info: { + * title: "Pet Store API", + * summary: "A sample API that uses a petstore as an example", + * description: "This is a sample server Petstore server.", + * termsOfService: "http://example.com/terms/", + * contact: { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }, + * license: { + * name: "Apache 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0.html" + * }, + * version: "1.0.0" + * }, + * servers: [ + * { + * url: "https://api.example.com/v1", + * description: "The production API server" + * } + * ], + * paths: { + * "/pets": { + * "get": { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * } + * } + * }, + * components: { + * schemas: { + * Pet: { + * type: "object", + * properties: { + * id: { type: "integer", format: "int64" }, + * name: { type: "string" } + * } + * } + * } + * }, + * tags: [ + * { + * name: "pets", + * description: "Pet store operations" + * } + * ] + * }; + * ``` + */ +export interface Specification extends Extension { + /** + * This string MUST be the version number of the OpenAPI Specification that the + * OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret + * the OpenAPI document. This is not related to the API `info.version` string. + * This field is required. + * + * @example "3.1.0" + * @example "3.1.1" + */ + openapi: string; + + /** + * Provides metadata about the API. The metadata MAY be used by tooling as required. + * This field is required. + * + * @example { title: "Pet Store API", version: "1.0.0" } + */ + info: Info; + + /** + * The default value for the `$schema` keyword within Schema Objects contained + * within this OAS document. This MUST be in the form of a URI. + * + * @example "https://json-schema.org/draft/2020-12/schema" + */ + jsonSchemaDialect?: string; + + /** + * An array of Server Objects, which provide connectivity information to a target + * server. If the `servers` property is not provided, or is an empty array, the + * default value would be a Server Object with a `url` value of `/`. + * + * @example [{ url: "https://api.example.com/v1", description: "The production API server" }] + */ + servers?: Server[]; + + /** + * The available paths and operations for the API. + * + * @example { "/pets": { "get": { "summary": "List all pets", "responses": { "200": { "description": "A list of pets" } } } } } + */ + paths?: Paths; + + /** + * The incoming webhooks that MAY be received as part of this API and that the + * API consumer MAY choose to implement. Closely related to the `callbacks` feature, + * this section describes requests initiated other than by an API call, for example + * by an out of band registration. + * + * @example { "newPet": { "post": { "requestBody": { "description": "Information about a new pet" } } } } + */ + webhooks?: Webhooks; + + /** + * An element to hold various schemas for the document. + * + * @example { schemas: { Pet: { type: "object", properties: { id: { type: "integer" } } } } } + */ + components?: Components; + + /** + * A declaration of which security mechanisms can be used across the API. The list + * of values includes alternative security requirement objects that can be used. + * Only one of the security requirement objects need to be satisfied to authorize + * a request. Individual operations can override this definition. + * + * @example [{ "api_key": [] }] + */ + security?: SecurityRequirement[]; + + /** + * A list of tags used by the document with additional metadata. The order of the + * tags can be used to reflect on their order by the parsing tools. Not all tags + * that are used by the Operation Object must be declared. The tags that are not + * declared MAY be organized randomly or based on the tools' logic. Each tag name + * in the list MUST be unique. + * + * @example [{ name: "pets", description: "Pet store operations" }] + */ + tags?: Tag[]; + + /** + * Additional external documentation. + * + * @example { description: "Find out more about our API", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; +} diff --git a/3.1/status.ts b/3.1/status.ts new file mode 100644 index 0000000..dd1f491 --- /dev/null +++ b/3.1/status.ts @@ -0,0 +1,999 @@ +import type { Response } from "./paths"; + +/** + * Swagger 2.0 Valid HTTP Status Codes + * + * Enumerates individual HTTP status codes (as keys) plus the special `"default"` key, + * per the IANA HTTP Status Code Registry. JSDoc reason phrases and references mirror + * the registry entries. See also RFC 9110 (HTTP Semantics) section mappings. + * + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA: HTTP Status Code Registry} + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html | RFC 9110: HTTP Semantics} + */ +export interface ResponsesMap { + //#region Family Codes + + /** 1xx — Informational + * + * Indicates that the request was received and the server is continuing to process it. + * + * Used for provisional responses that indicate the server has received the request and is continuing to process it. These responses are typically used for status updates during long-running operations or to indicate that the server is ready to receive additional data. + * + * The client should continue waiting for the final response. These are provisional responses and the client should not consider the request complete until receiving a final status code. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "1xx"?: Response; + + /** 2xx — Success + * + * Indicates that the request was successfully received, understood, and accepted. + * + * Used for successful operations where the request was processed successfully and the response contains the requested data or indicates successful completion of the operation. + * + * The operation completed successfully. The response body typically contains the requested data or confirmation of the successful operation. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "2xx"?: Response; + + /** 3xx — Redirection + * + * Indicates that further action needs to be taken by the client to complete the request. + * + * Used when the client needs to take additional action to complete the request, such as following a redirect, providing authentication, or accessing the resource at a different location. + * + * The client needs to take additional action to complete the request. This may involve following a redirect, providing authentication, or accessing the resource at a different location. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "3xx"?: Response; + + /** 4xx — Client Error + * + * Indicates that the request contains bad syntax or cannot be fulfilled by the server. + * + * Used when the client has sent an invalid request, such as malformed syntax, invalid parameters, authentication failures, or requests for non-existent resources. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "4xx"?: Response; + + /** 5xx — Server Error + * + * Indicates that the server failed to fulfill a valid request. + * + * Used when the server encounters an error while processing a valid request, such as internal server errors, service unavailability, or gateway timeouts. + * + * The server encountered an error while processing the request. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "5xx"?: Response; + + //#endregion + + //#region 1xx — Informational + + /** 100 Continue + * + * Indicates that the initial part of the request has been received and the client should continue with the request. + * + * The server has received the request headers and the client should proceed to send the request body. + * + * Used in scenarios where the client needs to send a large request body and wants to confirm the server is ready to receive it before sending the data. Commonly used with `Expect: 100-continue` header for file uploads, API requests with large payloads, or when implementing optimistic request patterns. + * + * The server is ready to process the request and the client can proceed with sending the request body. This prevents unnecessary data transmission if the server would reject the request based on headers alone. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-100-continue | RFC 9110 §15.2.1} + */ + "100"?: Response; + + /** 101 Switching Protocols + * + * Indicates that the server is switching protocols as requested by the client. + * + * The server agrees to change the application protocol within the current connection, typically from HTTP to WebSocket or other protocols. + * + * Primarily used for WebSocket connections where the client sends an `Upgrade: websocket` header and the server responds with 101 to establish the WebSocket connection. Also used for HTTP/2 upgrades, Server-Sent Events (SSE), or other protocol switching scenarios. + * + * The connection will continue using a different protocol. The response headers will contain the new protocol information, and subsequent communication will use the upgraded protocol. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-101-switching-protocols | RFC 9110 §15.2.2} + */ + "101"?: Response; + + /** 102 Processing + * + * Indicates that the server has received and is processing the request, but no response is available yet. + * + * The server has accepted the request and is processing it, but the processing is taking longer than normal and the client should continue waiting. + * + * Primarily used in WebDAV (Web Distributed Authoring and Versioning) environments for long-running operations like file uploads, batch operations, or complex data processing. Helps prevent client timeouts during extended processing periods. + * + * The request is being processed and the client should continue waiting. This prevents timeout issues during long-running operations and provides feedback that the server is actively working on the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2518 | RFC 2518 (WebDAV)} + */ + "102"?: Response; + + /** 103 Early Hints + * + * Provides early hints about the response that will be sent, allowing the client to start processing before the full response is ready. + * + * The server is sending preliminary information about the response headers and resources that will be needed, enabling the client to start optimization processes early. + * + * Used for performance optimization, particularly in web applications where the server can hint about resources (CSS, JavaScript, fonts) that will be needed for the final response. Allows browsers to start preloading resources before the main response is ready, significantly improving perceived performance. + * + * The client can start preparing for the response based on the hints provided. This is especially valuable for web applications where resource preloading can improve user experience. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8297 | RFC 8297} + */ + "103"?: Response; + + /** 104 Upload Resumption Supported — TEMPORARY + * + * Indicates that the server supports resumable uploads for the requested resource. + * + * The server is indicating that it can handle interrupted uploads and allows the client to resume uploading from where it left off. + * + * Used in file upload scenarios where large files might be interrupted due to network issues, browser crashes, or other problems. Enables clients to resume uploads without starting over, improving reliability for large file transfers and reducing bandwidth waste. + * + * The client can implement resumable upload logic, typically using range requests or specialized upload protocols. This is particularly valuable for mobile applications and unreliable network conditions. + * + * @note Temporary registration; see IANA entry for current status/expiry. + * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-resumable-upload-05 | draft-ietf-httpbis-resumable-upload-05} + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA registry} + */ + "104"?: Response; + + //#endregion + + //#region 2xx — Success + + /** 200 OK + * + * Indicates that the request has succeeded and the response contains the requested data. + * + * The request was processed successfully and the response body contains the requested resource or data. + * + * The most common success response for GET requests, API endpoints that return data, and successful operations. Used for retrieving resources, executing queries, and any operation that completes successfully with data to return. + * + * The operation completed successfully and the response body contains the requested information. This is the standard success response for most API operations. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok | RFC 9110 §15.3.1} + */ + "200"?: Response; + + /** 201 Created + * + * Indicates that the request has succeeded and a new resource has been created as a result. + * + * The request was processed successfully and resulted in the creation of a new resource. The response typically includes the location of the newly created resource. + * + * Used for POST requests that create new resources (users, posts, files, etc.). The response should include a `Location` header pointing to the newly created resource. Common in REST APIs for resource creation operations. + * + * A new resource was successfully created and the response contains information about the created resource, typically including its ID and location. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-201-created | RFC 9110 §15.3.2} + */ + "201"?: Response; + + /** 202 Accepted + * + * Indicates that the request has been accepted for processing, but the processing has not been completed. + * + * The request was valid and accepted, but the server will process it asynchronously. The processing may or may not eventually succeed. + * + * Used for asynchronous operations like background jobs, batch processing, email sending, or any operation that takes time to complete. The client should not assume the operation succeeded based on this response alone. + * + * The request was accepted and is being processed asynchronously. The client should check the status separately or wait for a callback/webhook to know the final result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted | RFC 9110 §15.3.3} + */ + "202"?: Response; + + /** 203 Non-Authoritative Information + * + * Indicates that the request was successful, but the information returned is from a transformed or cached version of the original resource. + * + * The response is successful but the data may have been modified by a transforming proxy or cache, and may not be the authoritative version. + * + * Used when responses come from caches, proxies, or transformation services where the data might be slightly different from the original. Common in CDN scenarios or when data is processed through middleware. + * + * The request succeeded but the response data may not be the most current or authoritative version. The client should be aware that the data might be cached or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-203-non-authoritative-informat | RFC 9110 §15.3.4} + */ + "203"?: Response; + + /** 204 No Content + * + * Indicates that the request has succeeded but there is no content to return in the response body. + * + * The request was processed successfully but the response body is intentionally empty. The client should not expect any content. + * + * Used for DELETE operations, PUT requests that don't return data, or any operation where success is indicated by the absence of content. Common in REST APIs for operations that modify state without returning data. + * + * The operation completed successfully but no data is returned. The client should not attempt to parse a response body. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-204-no-content | RFC 9110 §15.3.5} + */ + "204"?: Response; + + /** 205 Reset Content + * + * Indicates that the request has succeeded and the client should reset the document view that caused the request to be sent. + * + * The request was processed successfully and the client should clear any form data or reset the user interface state. + * + * Used in web applications where form submissions should clear the form after successful processing, or when the client needs to reset its state. Common in form handling and user interface operations. + * + * The operation succeeded and the client should reset its current state, typically clearing forms or resetting the user interface. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-205-reset-content | RFC 9110 §15.3.6} + */ + "205"?: Response; + + /** 206 Partial Content + * + * Indicates that the server is delivering only part of the resource due to a range request. + * + * The request included a Range header and the server is returning only the requested portion of the resource, along with information about the range delivered. + * + * Used for resumable downloads, video streaming, large file transfers, and any scenario where the client requests a specific portion of a resource. Enables efficient handling of large files and interrupted downloads. + * + * The response contains only a portion of the requested resource. The client should expect partial content and may need to make additional requests for the complete resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-206-partial-content | RFC 9110 §15.3.7} + */ + "206"?: Response; + + /** 207 Multi-Status + * + * Indicates that multiple independent operations might have been performed, and the status of each operation is reported in the response body. + * + * The response contains multiple status codes for different operations, typically in XML format with individual operation results. + * + * Used in WebDAV environments for batch operations, bulk file operations, or any scenario where multiple independent operations are performed in a single request. Common in file management systems and collaborative editing platforms. + * + * Multiple operations were attempted and the response contains the status of each individual operation. The client should parse the response body to determine which operations succeeded or failed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "207"?: Response; + + /** 208 Already Reported + * + * Indicates that the members of a DAV binding have already been enumerated in a previous response to this request, and are not being included again. + * + * Used in WebDAV to avoid repeating the same information in a multi-status response when the same binding has already been reported. + * + * Used in WebDAV environments to optimize responses by avoiding duplicate information in multi-status responses. Helps reduce response size and improve performance in complex file system operations. + * + * The information for this binding has already been reported in a previous part of the response. The client should not expect additional information for this specific binding. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "208"?: Response; + + /** 226 IM Used + * + * Indicates that the server has fulfilled a request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance. + * + * The response represents the result of applying instance manipulations (like delta encoding) to the current resource instance. + * + * Used in scenarios involving delta encoding, instance manipulations, or when the response represents a transformed version of the resource. Common in content delivery networks and systems that optimize data transmission. + * + * The response contains a manipulated version of the resource, typically optimized for transmission. The client should be aware that the data has been processed or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc3229 | RFC 3229} + */ + "226"?: Response; + + //#endregion + + //#region 3xx — Redirection + + /** 300 Multiple Choices + * + * Indicates that the request has multiple possible responses and the client should choose one. + * + * The server has multiple representations of the requested resource and the client must choose which one to use. + * + * Used when content negotiation results in multiple valid options, such as different formats (JSON, XML, HTML) or different languages. The response typically includes a list of available options with their characteristics. + * + * The client should examine the available options and make a choice, typically by sending another request with more specific preferences or headers. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-300-multiple-choices | RFC 9110 §15.4.1} + */ + "300"?: Response; + + /** 301 Moved Permanently + * + * Indicates that the requested resource has been permanently moved to a new location. + * + * The resource has been permanently relocated and all future requests should be directed to the new URL provided in the Location header. + * + * Used when resources are permanently relocated, such as when changing domain names, restructuring URLs, or moving content to new locations. Browsers and clients should update their bookmarks and caches. + * + * The resource has moved permanently and the client should update all references to use the new URL. Search engines and caches should update their indexes. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-301-moved-permanently | RFC 9110 §15.4.2} + */ + "301"?: Response; + + /** 302 Found + * + * Indicates that the requested resource has been temporarily moved to a different location. + * + * The resource is temporarily available at a different URL, but the original URL should continue to be used for future requests. + * + * Used for temporary redirects such as maintenance pages, temporary content moves, or when the resource is temporarily unavailable at the original location. The original URL remains valid. + * + * The resource is temporarily at a different location. The client should follow the redirect but continue using the original URL for future requests. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-302-found | RFC 9110 §15.4.3} + */ + "302"?: Response; + + /** 303 See Other + * + * Indicates that the response to the request can be found at a different URL and should be retrieved using a GET request. + * + * The request was processed but the response is available at a different location, and the client should use GET to retrieve it. + * + * Used in POST-redirect-GET patterns, form submissions that redirect to a results page, or when the response to a POST request should be retrieved via GET. Common in web applications for avoiding duplicate form submissions. + * + * The client should make a GET request to the provided URL to retrieve the response. This prevents duplicate submissions and provides a clean URL for the result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-303-see-other | RFC 9110 §15.4.4} + */ + "303"?: Response; + + /** 304 Not Modified + * + * Indicates that the resource has not been modified since the last request, so the cached version can be used. + * + * The resource has not changed since the last request, and the client can use its cached version. No response body is included. + * + * Used for caching optimization when the client sends conditional headers (If-Modified-Since, If-None-Match). Reduces bandwidth usage and improves performance by avoiding unnecessary data transfer. + * + * The resource has not changed and the client should use its cached version. This is an optimization response that saves bandwidth and improves performance. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-304-not-modified | RFC 9110 §15.4.5} + */ + "304"?: Response; + + /** 305 Use Proxy + * + * Indicates that the requested resource must be accessed through the proxy specified in the Location header. + * + * The client must use the specified proxy to access the resource. This response is rarely used in modern web applications. + * + * Used in corporate environments or specific network configurations where resources must be accessed through a particular proxy server. Mostly deprecated in modern web development. + * + * The client should use the specified proxy to access the resource. This is rarely encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy | RFC 9110 §15.4.6} + */ + "305"?: Response; + + /** 306 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code was previously used but is now reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-306-unused | RFC 9110 §15.4.7} + */ + "306"?: Response; + + /** 307 Temporary Redirect + * + * Indicates that the requested resource has been temporarily moved to a different location, and the request method should be preserved. + * + * The resource is temporarily available at a different URL, and the client should repeat the request using the same method to the new location. + * + * Used for temporary redirects where the HTTP method (POST, PUT, DELETE) should be preserved. Common in API versioning, temporary maintenance, or when resources are temporarily relocated. + * + * The resource is temporarily at a different location and the client should repeat the same request method to the new URL. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-307-temporary-redirect | RFC 9110 §15.4.8} + */ + "307"?: Response; + + /** 308 Permanent Redirect + * + * Indicates that the requested resource has been permanently moved to a different location, and the request method should be preserved. + * + * The resource has been permanently relocated and the client should use the new URL for all future requests, preserving the original HTTP method. + * + * Used for permanent redirects where the HTTP method should be preserved, such as when moving APIs to new endpoints or restructuring resource URLs. Common in API versioning and permanent relocations. + * + * The resource has moved permanently and the client should update all references to use the new URL while preserving the original HTTP method. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-308-permanent-redirect | RFC 9110 §15.4.9} + */ + "308"?: Response; + + //#endregion + + //#region 4xx — Client Error + + /** 400 Bad Request + * + * Indicates that the server cannot process the request due to a client error. + * + * The request syntax is invalid, malformed, or contains incorrect parameters that the server cannot understand or process. + * + * Used for validation errors, malformed JSON, missing required fields, invalid parameter values, or any client-side error that prevents the server from processing the request. Common in API validation scenarios. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request | RFC 9110 §15.5.1} + */ + "400"?: Response; + + /** 401 Unauthorized + * + * Indicates that the request requires authentication and the client has not provided valid credentials. + * + * The request lacks valid authentication credentials or the provided credentials are invalid, expired, or insufficient. + * + * Used when authentication is required but not provided, when login credentials are invalid, or when the authentication token has expired. Common in protected API endpoints and user authentication flows. + * + * The client needs to authenticate before accessing the resource. The response should include authentication challenge headers (WWW-Authenticate) indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized | RFC 9110 §15.5.2} + */ + "401"?: Response; + + /** 402 Payment Required + * + * Indicates that the request requires payment before it can be processed. + * + * The request cannot be fulfilled because payment is required. This status code is reserved for future use in digital payment systems. + * + * Used in payment-required scenarios, subscription services, or when access to a resource requires payment. Common in freemium models, paid API access, or premium content services. + * + * The client needs to provide payment information or complete a payment process before accessing the resource. The response should include information about how to make the payment. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required | RFC 9110 §15.5.3} + */ + "402"?: Response; + + /** 403 Forbidden + * + * Indicates that the server understood the request but refuses to authorize it. + * + * The client is authenticated but does not have permission to access the requested resource or perform the requested action. + * + * Used when the user is logged in but lacks the necessary permissions, when access is restricted based on user roles, or when the resource is not accessible to the current user. Common in authorization and access control scenarios. + * + * The client is authenticated but not authorized to access the resource. The client should not retry the request without additional permissions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden | RFC 9110 §15.5.4} + */ + "403"?: Response; + + /** 404 Not Found + * + * Indicates that the requested resource could not be found on the server. + * + * The server cannot find the requested resource at the specified URL, or the resource does not exist. + * + * Used when a resource doesn't exist, when the URL is incorrect, or when the requested item has been deleted. Common in web applications for missing pages, deleted content, or non-existent API endpoints. + * + * The requested resource does not exist. The client should verify the URL or check if the resource has been moved or deleted. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found | RFC 9110 §15.5.5} + */ + "404"?: Response; + + /** 405 Method Not Allowed + * + * Indicates that the HTTP method used in the request is not allowed for the requested resource. + * + * The resource exists but the HTTP method (GET, POST, PUT, DELETE, etc.) is not supported for this particular resource. + * + * Used when a resource only supports certain HTTP methods, such as a read-only endpoint that doesn't allow POST requests, or when the method is not implemented for the specific resource. Common in REST API design. + * + * The HTTP method is not allowed for this resource. The response should include an Allow header listing the permitted methods. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-405-method-not-allowed | RFC 9110 §15.5.6} + */ + "405"?: Response; + + /** 406 Not Acceptable + * + * Indicates that the server cannot produce a response matching the client's Accept headers. + * + * The server cannot generate a response in any of the formats requested by the client's Accept headers. + * + * Used when the client requests a specific content type (JSON, XML, HTML) that the server cannot provide, or when content negotiation fails. Common in API versioning and content type mismatches. + * + * The server cannot provide the requested content type. The client should check the Accept headers or request a different format. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable | RFC 9110 §15.5.7} + */ + "406"?: Response; + + /** 407 Proxy Authentication Required + * + * Indicates that the client must authenticate with the proxy server before the request can be processed. + * + * The proxy server requires authentication before it will forward the request to the destination server. + * + * Used in corporate environments or networks where proxy authentication is required. Common in enterprise networks, VPN connections, or when accessing resources through authenticated proxies. + * + * The client needs to authenticate with the proxy server. The response should include Proxy-Authenticate headers indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-req | RFC 9110 §15.5.8} + */ + "407"?: Response; + + /** 408 Request Timeout + * + * Indicates that the server timed out while waiting for the request from the client. + * + * The server did not receive a complete request within the time it was prepared to wait. + * + * Used when the client takes too long to send the complete request, when network issues cause delays, or when the server has a timeout policy for request processing. Common in slow network conditions or when clients fail to send complete requests. + * + * The request timed out and the client should retry the request. The client may need to optimize the request or check network connectivity. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-408-request-timeout | RFC 9110 §15.5.9} + */ + "408"?: Response; + + /** 409 Conflict + * + * Indicates that the request conflicts with the current state of the resource. + * + * The request cannot be completed due to a conflict with the current state of the resource, such as a version mismatch or concurrent modification. + * + * Used when trying to create a resource that already exists, when there's a version conflict in concurrent editing, or when the request conflicts with business rules. Common in collaborative editing, version control, and resource creation scenarios. + * + * The request conflicts with the current state of the resource. The client should resolve the conflict before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict | RFC 9110 §15.5.10} + */ + "409"?: Response; + + /** 410 Gone + * + * Indicates that the requested resource is no longer available and will not be available again. + * + * The resource has been permanently removed and will not be restored. This is different from 404, which indicates the resource was never found. + * + * Used when content has been permanently deleted, when resources have been removed and will not be restored, or when temporary content has expired. Common in content management systems and temporary resource scenarios. + * + * The resource has been permanently removed and will not be available again. The client should not retry the request and should update any references to this resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-410-gone | RFC 9110 §15.5.11} + */ + "410"?: Response; + + /** 411 Length Required + * + * Indicates that the server requires a Content-Length header in the request. + * + * The server cannot process the request without knowing the exact length of the request body. + * + * Used when the server needs to know the exact size of the request body before processing, such as for file uploads, large data transfers, or when implementing specific security measures. Common in file upload scenarios and certain API endpoints. + * + * The client must include a Content-Length header in the request. The client should retry the request with the proper Content-Length header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-411-length-required | RFC 9110 §15.5.12} + */ + "411"?: Response; + + /** 412 Precondition Failed + * + * Indicates that one or more preconditions in the request headers were not met. + * + * The server cannot meet the conditions specified in the request headers, such as If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-Since. + * + * Used in conditional requests where the client specifies conditions that must be met, such as version checking, cache validation, or optimistic concurrency control. Common in collaborative editing and caching scenarios. + * + * The preconditions in the request were not met. The client should check the conditions and retry the request with updated preconditions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-412-precondition-failed | RFC 9110 §15.5.13} + */ + "412"?: Response; + + /** 413 Content Too Large + * + * Indicates that the request payload is too large for the server to process. + * + * The request body exceeds the server's maximum allowed size limit. + * + * Used when file uploads exceed size limits, when request bodies are too large for processing, or when the server has configured size restrictions. Common in file upload scenarios and API rate limiting. + * + * The request payload is too large. The client should reduce the size of the request body or split it into smaller chunks. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-413-content-too-large | RFC 9110 §15.5.14} + */ + "413"?: Response; + + /** 414 URI Too Long + * + * Indicates that the URI provided in the request is too long for the server to process. + * + * The URL exceeds the server's maximum allowed length limit. + * + * Used when URLs are too long due to excessive query parameters, when GET requests contain too much data in the URL, or when the server has configured URI length restrictions. Common in search APIs and parameter-heavy requests. + * + * The URI is too long. The client should shorten the URL or use POST instead of GET for large amounts of data. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-414-uri-too-long | RFC 9110 §15.5.15} + */ + "414"?: Response; + + /** 415 Unsupported Media Type + * + * Indicates that the server cannot process the request because the media type is not supported. + * + * The server cannot process the request body because the Content-Type is not supported or recognized. + * + * Used when the client sends data in an unsupported format, when the server only accepts specific content types, or when there's a mismatch between the expected and actual content type. Common in API endpoints with strict content type requirements. + * + * The content type is not supported. The client should check the API documentation for supported content types and retry with the correct Content-Type header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type | RFC 9110 §15.5.16} + */ + "415"?: Response; + + /** 416 Range Not Satisfiable + * + * Indicates that the server cannot satisfy the range request specified in the Range header. + * + * The requested range is not valid for the resource, either because the range is beyond the resource size or the resource doesn't support range requests. + * + * Used when range requests are invalid, when the requested range exceeds the resource size, or when the resource doesn't support partial content requests. Common in file download scenarios and media streaming. + * + * The range request is not satisfiable. The client should check the range specification or request the full resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-416-range-not-satisfiable | RFC 9110 §15.5.17} + */ + "416"?: Response; + + /** 417 Expectation Failed + * + * Indicates that the server cannot meet the requirements of the Expect header. + * + * The server cannot fulfill the expectations specified in the Expect header, typically when the server cannot handle the 100-continue expectation. + * + * Used when the server cannot handle the Expect: 100-continue header, when the server doesn't support the expected behavior, or when there's a mismatch between client expectations and server capabilities. Common in HTTP/1.1 implementations. + * + * The server cannot meet the expectations in the request. The client should retry without the Expect header or adjust the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-417-expectation-failed | RFC 9110 §15.5.18} + */ + "417"?: Response; + + /** 418 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code is reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-418-unused | RFC 9110 §15.5.19} + */ + "418"?: Response; + + /** 421 Misdirected Request + * + * Indicates that the request was directed to a server that is not able to produce a response. + * + * The request was sent to a server that cannot handle it, typically due to HTTP/2 connection reuse issues or server configuration problems. + * + * Used in HTTP/2 environments when a request is sent to the wrong server due to connection reuse, when there are server configuration issues, or when the request cannot be processed by the current server instance. Common in load balancing scenarios. + * + * The request was sent to the wrong server. The client should retry the request, which may be routed to a different server. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-request | RFC 9110 §15.5.20} + */ + "421"?: Response; + + /** 422 Unprocessable Content + * + * Indicates that the request is well-formed but contains semantic errors that prevent processing. + * + * The request syntax is correct but the server cannot process the request due to semantic errors, such as validation failures or business rule violations. + * + * Used for validation errors, business rule violations, or when the request is syntactically correct but logically invalid. Common in API validation scenarios where the request format is correct but the data is invalid. + * + * The request is well-formed but contains semantic errors. The client should fix the data and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content | RFC 9110 §15.5.21} + */ + "422"?: Response; + + /** 423 Locked + * + * Indicates that the requested resource is locked and cannot be modified. + * + * The resource is locked by another process or user and cannot be accessed or modified at this time. + * + * Used in WebDAV environments for file locking, collaborative editing scenarios, or when resources are temporarily locked for maintenance. Common in document management systems and collaborative editing platforms. + * + * The resource is locked and cannot be accessed. The client should wait and retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "423"?: Response; + + /** 424 Failed Dependency + * + * Indicates that the request failed because it depended on another request that also failed. + * + * The request cannot be completed because it depends on another operation that failed, typically in batch or multi-part operations. + * + * Used in WebDAV environments for batch operations where one operation depends on another, or in complex workflows where operations have dependencies. Common in file management systems and collaborative editing scenarios. + * + * The request failed due to a dependency failure. The client should check the dependencies and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "424"?: Response; + + /** 425 Too Early + * + * Indicates that the server is unwilling to process the request because it might be replayed. + * + * The server is concerned that the request might be replayed and is unwilling to process it at this time, typically due to timing or security concerns. + * + * Used in scenarios where request replay is a security concern, such as in early data scenarios or when the server needs to prevent replay attacks. Common in security-sensitive applications and protocols. + * + * The server is unwilling to process the request due to replay concerns. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8470 | RFC 8470} + */ + "425"?: Response; + + /** 426 Upgrade Required + * + * Indicates that the server requires the client to upgrade to a different protocol. + * + * The server requires the client to use a different protocol version or upgrade to a newer version to access the resource. + * + * Used when the server requires protocol upgrades, when the client is using an outdated protocol version, or when the server only supports newer protocol versions. Common in API versioning and protocol migration scenarios. + * + * The client must upgrade to a different protocol version. The response should include upgrade information. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-426-upgrade-required | RFC 9110 §15.5.22} + */ + "426"?: Response; + + /** 428 Precondition Required + * + * Indicates that the server requires the request to include certain preconditions. + * + * The server requires the client to include specific preconditions in the request headers before it will process the request. + * + * Used when the server requires specific preconditions for security or consistency reasons, such as requiring If-Match headers for optimistic concurrency control or other conditional headers. Common in collaborative editing and version control scenarios. + * + * The server requires specific preconditions. The client should include the required preconditions and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "428"?: Response; + + /** 429 Too Many Requests + * + * Indicates that the client has sent too many requests in a given time period and should slow down. + * + * The client has exceeded the rate limit and the server is refusing to process additional requests until the rate limit resets. + * + * Used for rate limiting, API throttling, and preventing abuse. Common in API endpoints that need to control request frequency, prevent spam, or manage resource usage. Often includes retry-after headers. + * + * The client has exceeded the rate limit and should slow down. The client should wait before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "429"?: Response; + + /** 431 Request Header Fields Too Large + * + * Indicates that the server is unwilling to process the request because the header fields are too large. + * + * The request headers exceed the server's maximum allowed size limit. + * + * Used when request headers are too large, when there are too many headers, or when individual headers exceed size limits. Common in scenarios with large authentication tokens or excessive header data. + * + * The request headers are too large. The client should reduce the size of the headers and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "431"?: Response; + + /** 451 Unavailable For Legal Reasons + * + * Indicates that the requested resource is unavailable due to legal reasons. + * + * The resource is not available due to legal restrictions, such as censorship, court orders, or regulatory requirements. + * + * Used when content is blocked due to legal restrictions, when resources are unavailable in certain jurisdictions, or when there are regulatory compliance issues. Common in content delivery networks and international services. + * + * The resource is unavailable due to legal restrictions. The client should not retry the request as it will not be available. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc7725 | RFC 7725} + */ + "451"?: Response; + + //#endregion + + //#region 5xx — Server Error + + /** 500 Internal Server Error + * + * Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. + * + * The server encountered an internal error or exception that prevented it from processing the request successfully. + * + * Used for server-side errors, unhandled exceptions, database connection failures, or any unexpected server-side issue. Common in applications when there are bugs, configuration issues, or resource problems. + * + * The server encountered an internal error. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error | RFC 9110 §15.6.1} + */ + "500"?: Response; + + /** 501 Not Implemented + * + * Indicates that the server does not support the functionality required to fulfill the request. + * + * The server does not recognize the request method or lacks the ability to fulfill the request. + * + * Used when the server doesn't support the requested HTTP method, when functionality is not implemented, or when the server cannot handle the request. Common in API development when endpoints are not yet implemented. + * + * The server does not support the requested functionality. The client should check the API documentation for supported methods and features. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-501-not-implemented | RFC 9110 §15.6.2} + */ + "501"?: Response; + + /** 502 Bad Gateway + * + * Indicates that the server, while acting as a gateway or proxy, received an invalid response from an upstream server. + * + * The server acting as a gateway or proxy received an invalid response from the upstream server it was trying to access. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server returns an invalid response or is unreachable. Common in microservices architectures and distributed systems. + * + * The gateway received an invalid response from the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway | RFC 9110 §15.6.3} + */ + "502"?: Response; + + /** 503 Service Unavailable + * + * Indicates that the server is temporarily unable to handle the request due to maintenance or overload. + * + * The server is temporarily unavailable, typically due to maintenance, overload, or temporary resource constraints. + * + * Used during server maintenance, when the server is overloaded, when there are temporary resource issues, or when the service is temporarily down. Common in high-traffic scenarios and planned maintenance windows. + * + * The server is temporarily unavailable. The client should retry the request later, often with exponential backoff. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable | RFC 9110 §15.6.4} + */ + "503"?: Response; + + /** 504 Gateway Timeout + * + * Indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server. + * + * The gateway or proxy server timed out while waiting for a response from the upstream server. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server takes too long to respond. Common in microservices architectures where services have different response times. + * + * The gateway timed out waiting for the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-504-gateway-timeout | RFC 9110 §15.6.5} + */ + "504"?: Response; + + /** 505 HTTP Version Not Supported + * + * Indicates that the server does not support the HTTP protocol version used in the request. + * + * The server does not support the HTTP protocol version specified in the request. + * + * Used when the client uses an unsupported HTTP version, when the server only supports specific HTTP versions, or when there are protocol version mismatches. Common in legacy systems and protocol migration scenarios. + * + * The server does not support the HTTP version used in the request. The client should use a supported HTTP version. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-supporte | RFC 9110 §15.6.6} + */ + "505"?: Response; + + /** 506 Variant Also Negotiates + * + * Indicates that the server has an internal configuration error in which the chosen variant resource is configured to engage in transparent content negotiation. + * + * The server has a configuration error where the selected variant resource is configured to engage in transparent content negotiation, creating a negotiation loop. + * + * Used in content negotiation scenarios where there's a configuration error causing negotiation loops. Common in complex content delivery systems and advanced HTTP implementations. + * + * The server has a configuration error in content negotiation. The client should contact the server administrator. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2295 | RFC 2295} + */ + "506"?: Response; + + /** 507 Insufficient Storage + * + * Indicates that the server is unable to store the representation needed to complete the request. + * + * The server cannot store the representation required to complete the request, typically due to storage space limitations. + * + * Used in WebDAV environments when there's insufficient storage space, when the server cannot allocate storage for the request, or when storage quotas are exceeded. Common in file management systems and collaborative editing platforms. + * + * The server cannot store the required representation. The client should check storage availability and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "507"?: Response; + + /** 508 Loop Detected + * + * Indicates that the server detected an infinite loop while processing the request. + * + * The server detected an infinite loop in the request processing, typically in WebDAV operations. + * + * Used in WebDAV environments when there are infinite loops in request processing, when there are circular references in operations, or when the server detects recursive operations. Common in file management systems and collaborative editing scenarios. + * + * The server detected an infinite loop. The client should check the request for circular references and retry. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "508"?: Response; + + /** 510 Not Extended — OBSOLETED + * + * This status code is obsolete and should not be used in modern implementations. + * + * This status code was used for HTTP extensions but is now obsolete and should not be used. + * + * Not used in modern web applications. This code is obsolete and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2774 | RFC 2774 (Historic)} + * @see {@link https://datatracker.ietf.org/doc/status-change-http-experiments-to-historic/ | IETF: Status change of HTTP experiments to Historic} + */ + "510"?: Response; + + /** 511 Network Authentication Required + * + * Indicates that the client needs to authenticate to gain network access. + * + * The client must authenticate with the network before it can access the requested resource. + * + * Used in captive portal scenarios, public Wi-Fi networks, or when network-level authentication is required. Common in public networks, hotels, airports, and other locations where network access requires authentication. + * + * The client needs to authenticate with the network. The client should follow the authentication process provided by the network. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "511"?: Response; + + //#endregion + + /** default — The default response for all codes not covered individually. */ + default?: Response; +} diff --git a/3.1.x/tags.ts b/3.1/tags.ts similarity index 58% rename from 3.1.x/tags.ts rename to 3.1/tags.ts index 621e6d9..d775385 100644 --- a/3.1.x/tags.ts +++ b/3.1/tags.ts @@ -1,4 +1,4 @@ -import type { Extension } from "./extensions" +import type { Extension } from "./extensions"; /** * ----- @@ -21,10 +21,10 @@ import type { Extension } from "./extensions" * Fields * ----- * - * @key `name` - Required The name of the tag - * @key `description` - Optional A short description for the tag - * @key `externalDocs` - Optional Additional external documentation for this tag - * @key `x-${string}` - Specification Extensions + * @property `name` - Required The name of the tag + * @property `description` - Optional A short description for the tag + * @property `externalDocs` - Optional Additional external documentation for this tag + * @property `x-${string}` - Specification Extensions * * @note * The `name` field is required. @@ -54,29 +54,29 @@ import type { Extension } from "./extensions" * ``` */ export interface Tag extends Extension { - /** - * The name of the tag. This field is required. - * - * @example "users" - * @example "pets" - * @example "authentication" - */ - name: string + /** + * The name of the tag. This field is required. + * + * @example "users" + * @example "pets" + * @example "authentication" + */ + name: string; - /** - * A short description for the tag. CommonMark syntax MAY be used for rich text representation. - * - * @example "User management operations" - * @example "Pet store operations" - */ - description?: string + /** + * A short description for the tag. CommonMark syntax MAY be used for rich text representation. + * + * @example "User management operations" + * @example "Pet store operations" + */ + description?: string; - /** - * Additional external documentation for this tag. - * - * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } - */ - externalDocs?: ExternalDocumentation + /** + * Additional external documentation for this tag. + * + * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } + */ + externalDocs?: ExternalDocumentation; } /** @@ -95,9 +95,9 @@ export interface Tag extends Extension { * Fields * ----- * - * @key `description` - Optional A short description of the target documentation - * @key `url` - Required The URL for the target documentation - * @key `x-${string}` - Specification Extensions + * @property `description` - Optional A short description of the target documentation + * @property `url` - Required The URL for the target documentation + * @property `x-${string}` - Specification Extensions * * @note * The `url` field is required. @@ -122,21 +122,21 @@ export interface Tag extends Extension { * ``` */ export interface ExternalDocumentation extends Extension { - /** - * A short description of the target documentation. CommonMark syntax MAY be used - * for rich text representation. - * - * @example "Find out more about our API" - * @example "Additional documentation for this endpoint" - */ - description?: string + /** + * A short description of the target documentation. CommonMark syntax MAY be used + * for rich text representation. + * + * @example "Find out more about our API" + * @example "Additional documentation for this endpoint" + */ + description?: string; - /** - * The URL for the target documentation. This field is required and MUST be in the - * format of a URL. - * - * @example "https://example.com/docs" - * @example "https://docs.example.com/api" - */ - url: string + /** + * The URL for the target documentation. This field is required and MUST be in the + * format of a URL. + * + * @example "https://example.com/docs" + * @example "https://docs.example.com/api" + */ + url: string; } diff --git a/3.1/webhooks.ts b/3.1/webhooks.ts new file mode 100644 index 0000000..72c44e2 --- /dev/null +++ b/3.1/webhooks.ts @@ -0,0 +1,131 @@ +import type { Extension } from "./extensions"; +import type { PathItemObject } from "./paths"; +import type { Reference } from "./references"; + +/** + * ----- + * Webhooks Object + * ----- + * + * The incoming webhooks that MAY be received as part of this API and that the + * API consumer MAY choose to implement. Closely related to the `callbacks` feature, + * this section describes requests initiated other than by an API call, for example + * by an out of band registration. + * + * The key name is a unique string to refer to each webhook, while the (optionally + * referenced) Path Item Object describes a request that may be initiated by the + * API provider and the expected responses. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#webhooks-object | OpenAPI 3.1.1 Webhooks Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#webhooks-object | OpenAPI 3.1.0 Webhooks Object} | + * + * ----- + * Fields + * ----- + * + * @property `{webhookName}` - A unique string to refer to each webhook + * @property `PathItemObject` - The Path Item Object describing the webhook request + * @property `Reference` - A reference to a Path Item Object + * @property `x-${string}` - Specification Extensions + * + * @note + * Each webhook key must be a unique string identifier. The value can be either + * a Path Item Object or a Reference to a Path Item Object. + * + * ----- + * Examples + * ----- + * + * @example (simple webhook): + * ```ts + * const webhooks: Webhooks = { + * "newPet": { + * "post": { + * "requestBody": { + * "description": "Information about a new pet", + * "content": { + * "application/json": { + * "schema": { + * "$ref": "#/components/schemas/Pet" + * } + * } + * } + * }, + * "responses": { + * "200": { + * "description": "Webhook processed successfully" + * } + * } + * } + * } + * }; + * ``` + * + * @example (webhook with reference): + * ```ts + * const webhooks: Webhooks = { + * "petUpdated": { + * "$ref": "#/components/pathItems/PetUpdateWebhook" + * } + * }; + * ``` + * + * @example (multiple webhooks): + * ```ts + * const webhooks: Webhooks = { + * "newPet": { + * "post": { + * "summary": "New pet created", + * "requestBody": { + * "content": { + * "application/json": { + * "schema": { "$ref": "#/components/schemas/Pet" } + * } + * } + * }, + * "responses": { + * "200": { "description": "Success" } + * } + * } + * }, + * "petDeleted": { + * "delete": { + * "summary": "Pet deleted", + * "responses": { + * "200": { "description": "Success" } + * } + * } + * } + * }; + * ``` + * + * @example (webhook with multiple operations): + * ```ts + * const webhooks: Webhooks = { + * "petLifecycle": { + * "post": { + * "summary": "Pet created or updated", + * "requestBody": { + * "content": { + * "application/json": { + * "schema": { "$ref": "#/components/schemas/Pet" } + * } + * } + * }, + * "responses": { + * "200": { "description": "Success" } + * } + * }, + * "delete": { + * "summary": "Pet deleted", + * "responses": { + * "200": { "description": "Success" } + * } + * } + * } + * }; + * ``` + */ +export type Webhooks = Record & Extension; diff --git a/3.1/xml.ts b/3.1/xml.ts new file mode 100644 index 0000000..ba0704e --- /dev/null +++ b/3.1/xml.ts @@ -0,0 +1,117 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * XML Object + * ----- + * + * A metadata object that allows for more fine-tuned XML model definitions. + * + * When using arrays, XML element names are not inferred (for singular/plural forms) + * and the `name` property SHOULD be used to add that information. + * + * | Version | Reference | + * |---|-----| + * | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#xml-object | OpenAPI 3.1.1 XML Object} | + * | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#xml-object | OpenAPI 3.1.0 XML Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Optional Replaces the name of the element/attribute used for the described schema property + * @property `namespace` - Optional The URI of the namespace definition + * @property `prefix` - Optional The prefix to be used for the name + * @property `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element + * @property `wrapped` - Optional MAY be used only for an array definition. Signifies whether the array is wrapped + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. + * + * ----- + * Examples + * ----- + * + * @example (simple XML): + * ```ts + * const xml: XML = { + * name: "user" + * }; + * ``` + * + * @example (XML with namespace): + * ```ts + * const xml: XML = { + * name: "user", + * namespace: "http://example.com/schema/user", + * prefix: "user" + * }; + * ``` + * + * @example (XML attribute): + * ```ts + * const xml: XML = { + * name: "id", + * attribute: true + * }; + * ``` + * + * @example (wrapped array): + * ```ts + * const xml: XML = { + * name: "users", + * wrapped: true + * }; + * ``` + */ +export interface XML extends Extension { + /** + * Replaces the name of the element/attribute used for the described schema property. + * When defined within the Items Object (items), it will affect the name of the individual + * XML elements within the list. When defined alongside type being array (outside the items), + * it will affect the wrapping element and only if wrapped is true. If wrapped is false, + * it will be ignored. + * + * @example "user" + * @example "id" + * @example "users" + */ + name?: string; + + /** + * The URI of the namespace definition. This MUST be in the form of an absolute URI. + * + * @example "http://example.com/schema/user" + * @example "http://www.w3.org/XML/1998/namespace" + */ + namespace?: string; + + /** + * The prefix to be used for the name. + * + * @example "user" + * @example "xml" + */ + prefix?: string; + + /** + * Declares whether the property definition translates to an attribute instead of an element. + * Default value is false. + * + * @example true + * @example false + */ + attribute?: boolean; + + /** + * MAY be used only for an array definition. Signifies whether the array is wrapped + * (for example, ``) or unwrapped + * (for example, ``). Default value is false. The definition takes effect + * only when defined alongside type being array (outside the items). + * + * @example true + * @example false + */ + wrapped?: boolean; +} diff --git a/3.2.0/3.2.0.md b/3.2/3.2.0.md similarity index 100% rename from 3.2.0/3.2.0.md rename to 3.2/3.2.0.md diff --git a/3.2/components.ts b/3.2/components.ts new file mode 100644 index 0000000..646fbf7 --- /dev/null +++ b/3.2/components.ts @@ -0,0 +1,1223 @@ +import type { Extension } from "./extensions"; +import type { OAuthFlows } from "./oauth"; +import type { Parameter, PathItemObject } from "./paths"; +import type { Reference } from "./references"; +import type { Schema } from "./schema"; +import type { Server } from "./servers"; + +/** + * ----- + * Components Object + * ----- + * + * Holds a set of reusable objects for different aspects of the OAS. All objects defined + * within the components object will have no effect on the API unless they are explicitly + * referenced from properties outside the components object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object} | + * + * ----- + * Fields + * ----- + * + * @property `schemas` - An object to hold reusable Schema Objects + * @property `responses` - An object to hold reusable Response Objects + * @property `parameters` - An object to hold reusable Parameter Objects + * @property `examples` - An object to hold reusable Example Objects + * @property `requestBodies` - An object to hold reusable Request Body Objects + * @property `headers` - An object to hold reusable Header Objects + * @property `securitySchemes` - An object to hold reusable Security Scheme Objects + * @property `links` - An object to hold reusable Link Objects + * @property `callbacks` - An object to hold reusable Callback Objects + * @property `x-${string}` - Specification Extensions + * + * @note + * All objects defined within the components object will have no effect on the API unless + * they are explicitly referenced from properties outside the components object. + * + * ----- + * Examples + * ----- + * + * @example (basic components): + * ```ts + * const components: Components = { + * schemas: { + * User: { + * type: "object", + * properties: { + * id: { type: "integer" }, + * name: { type: "string" } + * } + * } + * } + * }; + * ``` + */ +export interface Components extends Extension { + /** + * An object to hold reusable Schema Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - schemas} | + * + * @property `schemas` - Optional An object to hold reusable Schema Objects + * + * @example { "User": { type: "object", properties: { id: { type: "integer" } } } } + */ + schemas?: Record; + + /** + * An object to hold reusable Response Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - responses} | + * + * @property `responses` - Optional An object to hold reusable Response Objects + * + * @example { "NotFound": { description: "Resource not found" } } + */ + responses?: Record; + + /** + * An object to hold reusable Parameter Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - parameters} | + * + * @property `parameters` - Optional An object to hold reusable Parameter Objects + * + * @example { "LimitParam": { name: "limit", in: "query", schema: { type: "integer" } } } + */ + parameters?: Record; + + /** + * An object to hold reusable Example Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - examples} | + * + * @property `examples` - Optional An object to hold reusable Example Objects + * + * @example { "UserExample": { summary: "A user example", value: { id: 1, name: "John" } } } + */ + examples?: Record; + + /** + * An object to hold reusable Request Body Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - requestBodies} | + * + * @property `requestBodies` - Optional An object to hold reusable Request Body Objects + * + * @example { "UserRequest": { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } } + */ + requestBodies?: Record; + + /** + * An object to hold reusable Header Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - headers} | + * + * @property `headers` - Optional An object to hold reusable Header Objects + * + * @example { "RateLimit": { description: "Rate limit header", schema: { type: "integer" } } } + */ + headers?: Record; + + /** + * An object to hold reusable Security Scheme Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - securitySchemes} | + * + * @property `securitySchemes` - Optional An object to hold reusable Security Scheme Objects + * + * @example { "ApiKeyAuth": { type: "apiKey", in: "header", name: "X-API-Key" } } + */ + securitySchemes?: Record; + + /** + * An object to hold reusable Link Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - links} | + * + * @property `links` - Optional An object to hold reusable Link Objects + * + * @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } } + */ + links?: Record; + + /** + * An object to hold reusable Callback Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#components-object | OpenAPI 3.2.0 Components Object - callbacks} | + * + * @property `callbacks` - Optional An object to hold reusable Callback Objects + * + * @example { "MyCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { $ref: "#/components/requestBodies/SomeRequestBody" } } } } } + */ + callbacks?: Record; +} + +/** + * ----- + * Response Object + * ----- + * + * Describes a single response from an API Operation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#response-object | OpenAPI 3.2.0 Response Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Required A short description of the response + * @property `headers` - Optional Maps a header name to its definition + * @property `content` - Optional A map containing descriptions of potential response payloads + * @property `links` - Optional A map of operations links that can be followed from the response + * @property `x-${string}` - Specification Extensions + * + * @note + * The `description` field is required. The `content` field is required for all responses except 204 No Content. + * + * ----- + * Examples + * ----- + * + * @example (basic response): + * ```ts + * const response: Response = { + * "description": "A list of pets", + * "content": { + * "application/json": { + * "schema": { + * "type": "array", + * "items": { "$ref": "#/components/schemas/Pet" } + * } + * } + * } + * }; + * ``` + */ +export interface Response extends Extension { + /** + * A short description of the response. CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#response-object | OpenAPI 3.2.0 Response Object - description} | + * + * @property `description` - Required A short description of the response + * + * @example "A list of pets" + * @example "User created successfully" + */ + description: string; + + /** + * Maps a header name to its definition. Header names are case insensitive. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#response-object | OpenAPI 3.2.0 Response Object - headers} | + * + * @property `headers` - Optional Maps a header name to its definition + * + * @example { "X-RateLimit-Limit": { description: "Rate limit", schema: { type: "integer" } } } + */ + headers?: Record; + + /** + * A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#response-object | OpenAPI 3.2.0 Response Object - content} | + * + * @property `content` - Optional A map containing descriptions of potential response payloads + * + * @example { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Pet" } } } } + */ + content?: Record; + + /** + * A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#response-object | OpenAPI 3.2.0 Response Object - links} | + * + * @property `links` - Optional A map of operations links that can be followed from the response + * + * @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } } + */ + links?: Record; +} + +/** + * ----- + * Header Object + * ----- + * + * The Header Object follows the structure of the Parameter Object with the following changes: + * 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map + * 2. `in` MUST NOT be specified, it is implicitly in `header` + * 3. All traits that are affected by the location MUST be applicable to a location of `header` (for example, `style`) + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A brief description of the header + * @property `required` - Optional Determines whether this header is mandatory + * @property `deprecated` - Optional Specifies that a header is deprecated + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued headers + * @property `style` - Optional Describes how the header value will be serialized + * @property `explode` - Optional When this is true, header values generate separate headers + * @property `allowReserved` - Optional Determines whether the header value SHOULD allow reserved characters + * @property `schema` - Optional The schema defining the type used for the header + * @property `example` - Optional Example of the header + * @property `examples` - Optional Examples of the header + * @property `content` - Optional A map containing the representations for the header + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` and `in` fields are not allowed in Header Objects. + * + * ----- + * Examples + * ----- + * + * @example (basic header): + * ```ts + * const header: Header = { + * "description": "Rate limit header", + * "schema": { "type": "integer" } + * }; + * ``` + */ +export interface Header extends Extension { + /** + * A brief description of the header. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - description} | + * + * @property `description` - Optional A brief description of the header + * + * @example "Rate limit header" + * @example "Authentication token" + */ + description?: string; + + /** + * Determines whether this header is mandatory. Default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - required} | + * + * @property `required` - Optional Determines whether this header is mandatory + * + * @example true + * @example false + */ + required?: boolean; + + /** + * Specifies that a header is deprecated and SHOULD be transitioned out of usage. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - deprecated} | + * + * @property `deprecated` - Optional Specifies that a header is deprecated and SHOULD be transitioned out of usage + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * Sets the ability to pass empty-valued headers. Default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - allowEmptyValue} | + * + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued headers + * + * @example true + * @example false + */ + allowEmptyValue?: boolean; + + /** + * Describes how the header value will be serialized. Default value is "simple". + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - style} | + * + * @property `style` - Optional Describes how the header value will be serialized + * + * @example "simple" + */ + style?: "simple"; + + /** + * When this is true, header values of type array or object generate separate headers + * for each value of the array or key-value pair of the map. For other types of headers + * this property has no effect. Default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - explode} | + * + * @property `explode` - Optional When this is true, header values of type array or object generate separate headers + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the header value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. Default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - allowReserved} | + * + * @property `allowReserved` - Optional Determines whether the header value SHOULD allow reserved characters + * + * @example true + * @example false + */ + allowReserved?: boolean; + + /** + * The schema defining the type used for the header. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - schema} | + * + * @property `schema` - Optional The schema defining the type used for the header + * + * @example { type: "integer" } + * @example { type: "string", format: "date-time" } + */ + schema?: Schema; + + /** + * Example of the header. The example SHOULD match the specified schema and encoding + * properties if present. The example object is mutually exclusive of the examples object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - example} | + * + * @property `example` - Optional Example of the header + * + * @example "example-value" + * @example 42 + */ + example?: unknown; + + /** + * Examples of the header. Each example SHOULD contain a value in the correct format + * as specified in the header encoding. The examples object is mutually exclusive of + * the example object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - examples} | + * + * @property `examples` - Optional Examples of the header + * + * @example { "header1": { summary: "A header example", value: "header123" } } + */ + examples?: Record; + + /** + * A map containing the representations for the header. The key is the media type + * and the value describes it. The map MUST only contain one entry. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#header-object | OpenAPI 3.2.0 Header Object - content} | + * + * @property `content` - Optional A map containing the representations for the header + * + * @example { "application/json": { schema: { type: "object" } } } + */ + content?: Record; +} + +/** + * ----- + * Example Object + * ----- + * + * In all cases, the example value is expected to be compatible with the type schema of its associated value. + * Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#example-object | OpenAPI 3.2.0 Example Object} | + * + * ----- + * Fields + * ----- + * + * @property `summary` - Optional Short description for the example + * @property `description` - Optional Long description for the example + * @property `value` - Optional Embedded literal example + * @property `externalValue` - Optional A URI that points to a literal example + * @property `x-${string}` - Specification Extensions + * + * @note + * The `value` and `externalValue` fields are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (basic example): + * ```ts + * const example: Example = { + * "summary": "A user example", + * "value": { "id": 1, "name": "John Doe" } + * }; + * ``` + */ +export interface Example extends Extension { + /** + * Short description for the example. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#example-object | OpenAPI 3.2.0 Example Object - summary} | + * + * @property `summary` - Optional Short description for the example + * + * @example "A user example" + * @example "Error response" + */ + summary?: string; + + /** + * Long description for the example. CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#example-object | OpenAPI 3.2.0 Example Object - description} | + * + * @property `description` - Optional Long description for the example + * + * @example "An example of a user object with all fields populated" + * @example "An example of an error response when the user is not found" + */ + description?: string; + + /** + * Embedded literal example. The value field and externalValue field are mutually exclusive. + * To represent examples of media types that cannot naturally represented in JSON or YAML, + * use a string value to contain the example, escaping where necessary. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#example-object | OpenAPI 3.2.0 Example Object - value} | + * + * @property `value` - Optional Embedded literal example + * + * @example { "id": 1, "name": "John Doe" } + * @example "example-value" + * @example 42 + */ + value?: unknown; + + /** + * A URI that points to a literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The value field and externalValue field are mutually exclusive. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#example-object | OpenAPI 3.2.0 Example Object - externalValue} | + * + * @property `externalValue` - Optional A URI that points to a literal example + * + * @example "https://example.org/examples/user-example.json" + * @example "https://example.org/examples/error-example.xml" + */ + externalValue?: string; +} + +/** + * ----- + * Request Body Object + * ----- + * + * Describes a single request body. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#request-body-object | OpenAPI 3.2.0 Request Body Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A brief description of the request body + * @property `content` - Required The content of the request body + * @property `required` - Optional Determines if the request body is required in the request + * @property `x-${string}` - Specification Extensions + * + * @note + * The `content` field is required. The `required` field defaults to false. + * + * ----- + * Examples + * ----- + * + * @example (basic request body): + * ```ts + * const requestBody: RequestBody = { + * "description": "User data", + * "content": { + * "application/json": { + * "schema": { "$ref": "#/components/schemas/User" } + * } + * } + * }; + * ``` + */ +export interface RequestBody extends Extension { + /** + * A brief description of the request body. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#request-body-object | OpenAPI 3.2.0 Request Body Object - description} | + * + * @property `description` - Optional A brief description of the request body + * + * @example "User data" + * @example "Pet information to add to the store" + */ + description?: string; + + /** + * The content of the request body. The key is a media type or media type range and the value describes it. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#request-body-object | OpenAPI 3.2.0 Request Body Object - content} | + * + * @property `content` - Required The content of the request body + * + * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } } + */ + content: Record; + + /** + * Determines if the request body is required in the request. Defaults to false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#request-body-object | OpenAPI 3.2.0 Request Body Object - required} | + * + * @property `required` - Optional Determines if the request body is required in the request + * + * @example true + * @example false + */ + required?: boolean; +} + +/** + * ----- + * Security Scheme Object + * ----- + * + * Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, + * an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows + * (implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object} | + * + * ----- + * Fields + * ----- + * + * @property `type` - Required The type of the security scheme + * @property `description` - Optional A short description for security scheme + * @property `name` - Optional The name of the header, query or cookie parameter to be used + * @property `in` - Optional The location of the API key + * @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header + * @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted + * @property `flows` - Optional An object containing configuration information for the flow types supported + * @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values + * @property `x-${string}` - Specification Extensions + * + * @note + * The `type` field is required. Other fields depend on the security scheme type. + * + * ----- + * Examples + * ----- + * + * @example (API key): + * ```ts + * const securityScheme: SecurityScheme = { + * "type": "apiKey", + * "in": "header", + * "name": "X-API-Key" + * }; + * ``` + */ +export interface SecurityScheme extends Extension { + /** + * The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect". + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - type} | + * + * @property `type` - Required The type of the security scheme + * + * @example "apiKey" + * @example "http" + * @example "oauth2" + * @example "openIdConnect" + */ + type: "apiKey" | "http" | "oauth2" | "openIdConnect"; + + /** + * A short description for security scheme. CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - description} | + * + * @property `description` - Optional A short description for security scheme + * + * @example "API key authentication" + * @example "OAuth2 authentication" + */ + description?: string; + + /** + * The name of the header, query or cookie parameter to be used. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - name} | + * + * @property `name` - Optional The name of the header, query or cookie parameter to be used + * + * @example "X-API-Key" + * @example "Authorization" + */ + name?: string; + + /** + * The location of the API key. Valid values are "query", "header" or "cookie". + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - in} | + * + * @property `in` - Optional The location of the API key + * + * @example "query" + * @example "header" + * @example "cookie" + */ + in?: "query" | "header" | "cookie"; + + /** + * The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - scheme} | + * + * @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header + * + * @example "basic" + * @example "bearer" + * @example "digest" + */ + scheme?: string; + + /** + * A hint to the client to identify how the bearer token is formatted. Bearer tokens are not necessarily + * generated by an authorization server, so this field is a hint only. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - bearerFormat} | + * + * @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted + * + * @example "JWT" + * @example "OAuth2" + */ + bearerFormat?: string; + + /** + * An object containing configuration information for the flow types supported. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - flows} | + * + * @property `flows` - Optional An object containing configuration information for the flow types supported + * + * @example { "implicit": { authorizationUrl: "https://example.com/oauth/authorize", scopes: { "read": "Read access" } } } + */ + flows?: OAuthFlows; + + /** + * OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-scheme-object | OpenAPI 3.2.0 Security Scheme Object - openIdConnectUrl} | + * + * @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values + * + * @example "https://example.com/.well-known/openid_configuration" + */ + openIdConnectUrl?: string; +} + +/** + * ----- + * Link Object + * ----- + * + * The Link object represents a possible design-time link for a response. The presence of a link does not guarantee + * the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism + * between responses and other operations. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object} | + * + * ----- + * Fields + * ----- + * + * @property `operationRef` - Optional A relative or absolute reference to an OAS operation + * @property `operationId` - Optional The name of an existing, resolvable OAS operation + * @property `parameters` - Optional A map representing parameters to pass to an operation + * @property `requestBody` - Optional A literal value or expression to be evaluated and passed to the linked operation + * @property `description` - Optional A description of the link + * @property `server` - Optional A server object to be used by the target operation + * @property `x-${string}` - Specification Extensions + * + * @note + * Either `operationRef` or `operationId` MUST be specified. + * + * ----- + * Examples + * ----- + * + * @example (basic link): + * ```ts + * const link: Link = { + * "operationId": "getUserRepositories", + * "parameters": { + * "username": "$response.body#/username" + * } + * }; + * ``` + */ +export interface Link extends Extension { + /** + * A relative or absolute reference to an OAS operation. This field is mutually exclusive of the operationId field. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object - operationRef} | + * + * @property `operationRef` - Optional A relative or absolute reference to an OAS operation + * + * @example "#/paths/~12.0~1repositories~1{username}/get" + * @example "https://example.com/openapi.json#/paths/~12.0~1repositories~1{username}/get" + */ + operationRef?: string; + + /** + * The name of an existing, resolvable OAS operation. This field is mutually exclusive of the operationRef field. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object - operationId} | + * + * @property `operationId` - Optional The name of an existing, resolvable OAS operation + * + * @example "getUserRepositories" + * @example "getUserById" + */ + operationId?: string; + + /** + * A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object - parameters} | + * + * @property `parameters` - Optional A map representing parameters to pass to an operation + * + * @example { "username": "$response.body#/username" } + * @example { "id": "$response.body#/id" } + */ + parameters?: Record; + + /** + * A literal value or expression to be evaluated and passed to the linked operation as a request body. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object - requestBody} | + * + * @property `requestBody` - Optional A literal value or expression to be evaluated and passed to the linked operation + * + * @example "$request.body#/user" + * @example { "name": "John Doe" } + */ + requestBody?: RequestBody | Reference; + + /** + * A description of the link. CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object - description} | + * + * @property `description` - Optional A description of the link + * + * @example "Link to user repositories" + * @example "Link to user profile" + */ + description?: string; + + /** + * A server object to be used by the target operation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#link-object | OpenAPI 3.2.0 Link Object - server} | + * + * @property `server` - Optional A server object to be used by the target operation + * + * @example { "url": "https://api.example.com/v2" } + */ + server?: Server; +} + +/** + * ----- + * Callback Object + * ----- + * + * A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object + * that describes a set of requests that may be initiated by the API provider and the expected responses. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#callback-object | OpenAPI 3.2.0 Callback Object} | + * + * ----- + * Fields + * ----- + * + * @property `{expression}` - A Path Item Object that describes a set of requests that may be initiated by the API provider + * @property `x-${string}` - Specification Extensions + * + * @note + * The key is a runtime expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request. + * + * ----- + * Examples + * ----- + * + * @example (basic callback): + * ```ts + * const callback: Callback = { + * "{$request.body#/callbackUrl}": { + * "post": { + * "requestBody": { + * "$ref": "#/components/requestBodies/SomeRequestBody" + * } + * } + * } + * }; + * ``` + */ +export interface Callback { + [expression: string]: PathItemObject | Reference | unknown; +} + +/** + * ----- + * Encoding Object + * ----- + * + * A single encoding definition applied to a single schema property. + * The Encoding Object is used to describe how a specific property value will be serialized. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#encoding-object | OpenAPI 3.2.0 Encoding Object} | + * + * ----- + * Fields + * ----- + * + * @property `contentType` - Optional The Content-Type for encoding a specific property + * @property `headers` - Optional A map allowing additional information to be provided as headers + * @property `style` - Optional Describes how a specific property value will be serialized + * @property `explode` - Optional When this is true, property values of type array or object generate separate parameters + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * + * @note + * The Encoding Object is used in Media Type Objects for multipart and form-urlencoded content. + * + * ----- + * Examples + * ----- + * + * @example (basic encoding): + * ```ts + * const encoding: Encoding = { + * contentType: "text/plain" + * }; + * ``` + * + * @example (with style and explode): + * ```ts + * const encoding: Encoding = { + * style: "form", + * explode: true, + * allowReserved: false + * }; + * ``` + */ +export interface Encoding extends Extension { + /** + * The Content-Type for encoding a specific property. + * Default value depends on the property type: for string with format being binary – application/octet-stream; + * for other primitive types – text/plain; for object – application/json; for array – the default is defined based on the inner type. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#encoding-object | OpenAPI 3.2.0 Encoding Object - contentType} | + * + * @property `contentType` - Optional The Content-Type for encoding a specific property + * + * @example "text/plain" + * @example "application/json" + * @example "image/png" + */ + contentType?: string; + + /** + * A map allowing additional information to be provided as headers. + * For example, Content-Disposition. Content-Type is described separately and SHALL be ignored in this section. + * This property SHALL be ignored if the request body media is not a multipart. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#encoding-object | OpenAPI 3.2.0 Encoding Object - headers} | + * + * @property `headers` - Optional A map allowing additional information to be provided as headers + * + * @example { "Content-Disposition": { schema: { type: "string" } } } + */ + headers?: Record; + + /** + * Describes how a specific property value will be serialized depending on its type. + * See Parameter Object for details on the style property. The behavior follows the same values as query parameters. + * Default value depends on the property type: for string with format being binary – binary; for other primitive types – form. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#encoding-object | OpenAPI 3.2.0 Encoding Object - style} | + * + * @property `style` - Optional Describes how a specific property value will be serialized + * + * @example "form" + * @example "spaceDelimited" + * @example "pipeDelimited" + * @example "deepObject" + */ + style?: "form" | "spaceDelimited" | "pipeDelimited" | "deepObject"; + + /** + * When this is true, property values of type array or object generate separate parameters + * for each value of the array or key-value pair of the map. For other types of properties + * this property has no effect. When style is form, the default value is true. + * For all other styles, the default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#encoding-object | OpenAPI 3.2.0 Encoding Object - explode} | + * + * @property `explode` - Optional When this is true, property values of type array or object generate separate parameters + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the parameter value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#encoding-object | OpenAPI 3.2.0 Encoding Object - allowReserved} | + * + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * + * @example true + * @example false + */ + allowReserved?: boolean; +} + +/** + * ----- + * Media Type Object + * ----- + * + * Each Media Type Object provides schema and examples for the media type identified by its key. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#media-type-object | OpenAPI 3.2.0 Media Type Object} | + * + * ----- + * Fields + * ----- + * + * @property `schema` - Optional The schema defining the content of the request, response, or parameter + * @property `example` - Optional Example of the media type + * @property `examples` - Optional Examples of the media type + * @property `encoding` - Optional A map between a property name and its encoding information + * @property `x-${string}` - Specification Extensions + * + * @note + * The `example` and `examples` fields are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (basic media type): + * ```ts + * const mediaType: MediaType = { + * "schema": { + * "type": "object", + * "properties": { + * "id": { "type": "integer" }, + * "name": { "type": "string" } + * } + * } + * }; + * ``` + */ +export interface MediaType extends Extension { + /** + * The schema defining the content of the request, response, or parameter. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#media-type-object | OpenAPI 3.2.0 Media Type Object - schema} | + * + * @property `schema` - Optional The schema defining the content of the request, response, or parameter + * + * @example { type: "object", properties: { id: { type: "integer" } } } + * @example { $ref: "#/components/schemas/User" } + */ + schema?: Schema; + + /** + * Example of the media type. The example SHOULD match the specified schema and encoding + * properties if present. The example object is mutually exclusive of the examples object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#media-type-object | OpenAPI 3.2.0 Media Type Object - example} | + * + * @property `example` - Optional Example of the media type + * + * @example { "id": 1, "name": "John Doe" } + * @example "example-value" + */ + example?: unknown; + + /** + * Examples of the media type. Each example SHOULD contain a value in the correct format + * as specified in the media type encoding. The examples object is mutually exclusive of + * the example object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#media-type-object | OpenAPI 3.2.0 Media Type Object - examples} | + * + * @property `examples` - Optional Examples of the media type + * + * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } } + */ + examples?: Record; + + /** + * A map between a property name and its encoding information. The key, being the property name, + * MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody + * objects when the media type is multipart or application/x-www-form-urlencoded. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#media-type-object | OpenAPI 3.2.0 Media Type Object - encoding} | + * + * @property `encoding` - Optional A map between a property name and its encoding information + * + * @example { "name": { contentType: "text/plain" } } + */ + encoding?: Record; +} diff --git a/3.2/data-types/array.ts b/3.2/data-types/array.ts new file mode 100644 index 0000000..13309c4 --- /dev/null +++ b/3.2/data-types/array.ts @@ -0,0 +1,202 @@ +import type { Extension } from "../extensions"; +import type { Schema } from "../schema"; + +/** + * ----- + * Array Schema + * ----- + * + * A schema for array values. Includes array-specific validation properties + * that are only valid when `type: "array"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#data-types | OpenAPI 3.2.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "array"` - Required The type identifier for array schemas + * @property `items` - Optional Schema for array items + * @property `prefixItems` - Optional Schema for array items at specific positions + * @property `contains` - Optional Schema that array must contain at least one item matching + * @property `minContains` - Optional Minimum number of items that must match contains + * @property `maxContains` - Optional Maximum number of items that must match contains + * @property `minItems` - Optional Minimum number of items in the array + * @property `maxItems` - Optional Maximum number of items in the array + * @property `uniqueItems` - Optional Whether array items must be unique + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "array". + * + * ----- + * Examples + * ----- + * + * @example (basic array): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" } + * }; + * ``` + * + * @example (array with validation): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" }, + * minItems: 1, + * maxItems: 10, + * uniqueItems: true + * }; + * ``` + * + * @example (array with prefixItems): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * prefixItems: [ + * { type: "string" }, + * { type: "number" } + * ] + * }; + * ``` + * + * @example (array with contains): + * ```ts + * const arraySchema: ArraySchema = { + * type: "array", + * items: { type: "string" }, + * contains: { type: "string", enum: ["admin"] }, + * minContains: 1 + * }; + * ``` + */ +export interface ArraySchema extends Extension { + /** + * The type identifier for array schemas. + * Must be "array". + */ + type: "array"; + + /** + * The schema for array items. + * All items in the array must conform to this schema. + * + * Example: `{ type: "string" }` + */ + items?: Schema; + + /** + * The schema for array items at specific positions. + * Items at position i must conform to the schema at index i. + * + * Example: `[{ type: "string" }, { type: "number" }]` + */ + prefixItems?: Schema[]; + + /** + * The schema that the array must contain at least one item matching. + * At least one item in the array must conform to this schema. + * + * Example: `{ type: "string", enum: ["admin"] }` + */ + contains?: Schema; + + /** + * The minimum number of items that must match the contains schema. + * Must be a non-negative integer. + * + * Example: `1` + */ + minContains?: number; + + /** + * The maximum number of items that must match the contains schema. + * Must be a non-negative integer. + * + * Example: `5` + */ + maxContains?: number; + + /** + * The minimum number of items in the array. + * Must be a non-negative integer. + * + * Example: `1` + */ + minItems?: number; + + /** + * The maximum number of items in the array. + * Must be a non-negative integer. + * + * Example: `10` + */ + maxItems?: number; + + /** + * Whether array items must be unique. + * If true, all items in the array must be unique. + * + * Example: `true` + */ + uniqueItems?: boolean; + + /** + * An array of allowed values for the array. + * The value must be one of the values in this array. + * + * Example: `[["a", "b"], ["c", "d"]]` + */ + enum?: unknown[]; + + /** + * A single allowed value for the array. + * The value must be exactly this value. + * + * Example: `["a", "b"]` + */ + const?: unknown; + + /** + * An array of example values for the array. + * These are for documentation purposes only. + * + * Example: `[["a", "b"], ["c", "d"]]` + */ + examples?: unknown[]; + + /** + * The default value for the array. + * This value will be used if no value is provided. + * + * Example: `[]` + */ + default?: unknown[]; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User Tags"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"Array of user tags"` + */ + description?: string; +} diff --git a/3.2/data-types/boolean.ts b/3.2/data-types/boolean.ts new file mode 100644 index 0000000..7cee6b7 --- /dev/null +++ b/3.2/data-types/boolean.ts @@ -0,0 +1,120 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Boolean Schema + * ----- + * + * A schema for boolean values. Includes common validation properties + * that are only valid when `type: "boolean"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#data-types | OpenAPI 3.2.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "boolean"` - Required The type identifier for boolean schemas + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "boolean". + * + * ----- + * Examples + * ----- + * + * @example (basic boolean): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean" + * }; + * ``` + * + * @example (boolean with default): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * default: false + * }; + * ``` + * + * @example (boolean with enum): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * enum: [true, false] + * }; + * ``` + * + * @example (boolean with const): + * ```ts + * const booleanSchema: BooleanSchema = { + * type: "boolean", + * const: true + * }; + * ``` + */ +export interface BooleanSchema extends Extension { + /** + * The type identifier for boolean schemas. + * Must be "boolean". + */ + type: "boolean"; + + /** + * An array of allowed values for the boolean. + * The value must be one of the values in this array. + * + * Example: `[true, false]` + */ + enum?: boolean[]; + + /** + * A single allowed value for the boolean. + * The value must be exactly this value. + * + * Example: `true` + */ + const?: boolean; + + /** + * An array of example values for the boolean. + * These are for documentation purposes only. + * + * Example: `[true, false]` + */ + examples?: boolean[]; + + /** + * The default value for the boolean. + * This value will be used if no value is provided. + * + * Example: `false` + */ + default?: boolean; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"Is Active"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"Whether the user is active"` + */ + description?: string; +} diff --git a/3.2/data-types/composition.ts b/3.2/data-types/composition.ts new file mode 100644 index 0000000..9838798 --- /dev/null +++ b/3.2/data-types/composition.ts @@ -0,0 +1,189 @@ +import type { Extension } from "../extensions"; +import type { Schema } from "../schema"; + +/** + * ----- + * Composition Schema + * ----- + * + * A schema that uses composition keywords (allOf, anyOf, oneOf, not). + * These keywords are mutually exclusive with $ref, but otherwise can + * appear with any validation keywords. This schema type supports + * advanced JSON Schema 2020-12 features like conditional schemas. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#schema-object | OpenAPI 3.2.0 Schema Object} | + * + * ----- + * Fields + * ----- + * + * @property `allOf` - Optional Array of schemas that must all be satisfied + * @property `anyOf` - Optional Array of schemas where at least one must be satisfied + * @property `oneOf` - Optional Array of schemas where exactly one must be satisfied + * @property `not` - Optional Schema that must not be satisfied + * @property `if` - Optional Schema for conditional validation + * @property `then` - Optional Schema to apply if if condition is met + * @property `else` - Optional Schema to apply if if condition is not met + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * Composition keywords are mutually exclusive with $ref. At least one composition + * keyword must be present. The `if`/`then`/`else` keywords work together for + * conditional validation. + * + * ----- + * Examples + * ----- + * + * @example (allOf composition): + * ```ts + * const compositionSchema: CompositionSchema = { + * allOf: [ + * { type: "object", properties: { name: { type: "string" } } }, + * { type: "object", properties: { age: { type: "number" } } } + * ] + * }; + * ``` + * + * @example (anyOf composition): + * ```ts + * const compositionSchema: CompositionSchema = { + * anyOf: [ + * { type: "string" }, + * { type: "number" } + * ] + * }; + * ``` + * + * @example (oneOf composition): + * ```ts + * const compositionSchema: CompositionSchema = { + * oneOf: [ + * { type: "string", enum: ["active"] }, + * { type: "string", enum: ["inactive"] } + * ] + * }; + * ``` + * + * @example (conditional schema): + * ```ts + * const compositionSchema: CompositionSchema = { + * if: { type: "object", properties: { type: { const: "user" } } }, + * then: { type: "object", properties: { name: { type: "string" } } }, + * else: { type: "object", properties: { id: { type: "string" } } } + * }; + * ``` + */ +export interface CompositionSchema extends Extension { + /** + * An array of schemas that must all be satisfied. + * The value must conform to all schemas in the array. + * + * Example: `[{ type: "object" }, { properties: { name: { type: "string" } } }]` + */ + allOf?: Schema[]; + + /** + * An array of schemas where at least one must be satisfied. + * The value must conform to at least one schema in the array. + * + * Example: `[{ type: "string" }, { type: "number" }]` + */ + anyOf?: Schema[]; + + /** + * An array of schemas where exactly one must be satisfied. + * The value must conform to exactly one schema in the array. + * + * Example: `[{ type: "string" }, { type: "number" }]` + */ + oneOf?: Schema[]; + + /** + * A schema that must not be satisfied. + * The value must not conform to this schema. + * + * Example: `{ type: "string" }` + */ + not?: Schema; + + /** + * A schema for conditional validation. + * Used with `then` and `else` for conditional logic. + * + * Example: `{ type: "object", properties: { type: { const: "user" } } }` + */ + if?: Schema; + + /** + * A schema to apply if the `if` condition is met. + * The value must conform to this schema if the `if` schema is satisfied. + * + * Example: `{ type: "object", properties: { name: { type: "string" } } }` + */ + then?: Schema; + + /** + * A schema to apply if the `if` condition is not met. + * The value must conform to this schema if the `if` schema is not satisfied. + * + * Example: `{ type: "object", properties: { id: { type: "string" } } }` + */ + else?: Schema; + + /** + * An array of allowed values. + * The value must be one of the values in this array. + * + * Example: `["active", "inactive"]` + */ + enum?: unknown[]; + + /** + * A single allowed value. + * The value must be exactly this value. + * + * Example: `"active"` + */ + const?: unknown; + + /** + * An array of example values. + * These are for documentation purposes only. + * + * Example: `["example1", "example2"]` + */ + examples?: unknown[]; + + /** + * The default value. + * This value will be used if no value is provided. + * + * Example: `"default"` + */ + default?: unknown; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"Composed Schema"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"A schema composed of multiple schemas"` + */ + description?: string; +} diff --git a/3.2/data-types/index.ts b/3.2/data-types/index.ts new file mode 100644 index 0000000..1c9f258 --- /dev/null +++ b/3.2/data-types/index.ts @@ -0,0 +1,8 @@ +export type { ArraySchema } from "./array"; +export type { BooleanSchema } from "./boolean"; +export type { CompositionSchema } from "./composition"; +export type { IntegerSchema } from "./integer"; +export type { NumberSchema } from "./number"; +export type { ObjectSchema } from "./object"; +export type { ReferenceSchema } from "./reference"; +export type { StringSchema } from "./string"; diff --git a/3.2/data-types/integer.ts b/3.2/data-types/integer.ts new file mode 100644 index 0000000..9ea2acc --- /dev/null +++ b/3.2/data-types/integer.ts @@ -0,0 +1,177 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Integer Schema + * ----- + * + * A schema for integer values. Includes integer-specific validation properties + * that are only valid when `type: "integer"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#data-types | OpenAPI 3.2.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "integer"` - Required The type identifier for integer schemas + * @property `format` - Optional The format of the integer + * @property `multipleOf` - Optional Integer must be a multiple of this value + * @property `maximum` - Optional Maximum value (inclusive) + * @property `minimum` - Optional Minimum value (inclusive) + * @property `exclusiveMaximum` - Optional Maximum value (exclusive) + * @property `exclusiveMinimum` - Optional Minimum value (exclusive) + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "integer". + * + * ----- + * Examples + * ----- + * + * @example (basic integer): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer" + * }; + * ``` + * + * @example (integer with format and validation): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * format: "int32", + * minimum: 0, + * maximum: 100 + * }; + * ``` + * + * @example (integer with multipleOf): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * multipleOf: 5 + * }; + * ``` + * + * @example (integer with exclusive bounds): + * ```ts + * const integerSchema: IntegerSchema = { + * type: "integer", + * exclusiveMinimum: 0, + * exclusiveMaximum: 100 + * }; + * ``` + */ +export interface IntegerSchema extends Extension { + /** + * The type identifier for integer schemas. + * Must be "integer". + */ + type: "integer"; + + /** + * The format of the integer. + * See OpenAPI 3.2.0 Data Type Formats for further details. + * + * Example: `"int32"`, `"int64"` + */ + format?: string; + + /** + * The integer must be a multiple of this value. + * Must be a positive integer. + * + * Example: `5` + */ + multipleOf?: number; + + /** + * The maximum value of the integer (inclusive). + * The integer must be less than or equal to this value. + * + * Example: `100` + */ + maximum?: number; + + /** + * The minimum value of the integer (inclusive). + * The integer must be greater than or equal to this value. + * + * Example: `0` + */ + minimum?: number; + + /** + * The maximum value of the integer (exclusive). + * The integer must be less than this value. + * + * Example: `100` + */ + exclusiveMaximum?: number; + + /** + * The minimum value of the integer (exclusive). + * The integer must be greater than this value. + * + * Example: `0` + */ + exclusiveMinimum?: number; + + /** + * An array of allowed values for the integer. + * The value must be one of the values in this array. + * + * Example: `[1, 2, 3, 4, 5]` + */ + enum?: number[]; + + /** + * A single allowed value for the integer. + * The value must be exactly this value. + * + * Example: `42` + */ + const?: number; + + /** + * An array of example values for the integer. + * These are for documentation purposes only. + * + * Example: `[1, 2, 3]` + */ + examples?: number[]; + + /** + * The default value for the integer. + * This value will be used if no value is provided. + * + * Example: `0` + */ + default?: number; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User ID"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"The unique identifier of the user"` + */ + description?: string; +} diff --git a/3.2/data-types/number.ts b/3.2/data-types/number.ts new file mode 100644 index 0000000..7e73c3c --- /dev/null +++ b/3.2/data-types/number.ts @@ -0,0 +1,177 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Number Schema + * ----- + * + * A schema for number values. Includes number-specific validation properties + * that are only valid when `type: "number"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#data-types | OpenAPI 3.2.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "number"` - Required The type identifier for number schemas + * @property `format` - Optional The format of the number + * @property `multipleOf` - Optional Number must be a multiple of this value + * @property `maximum` - Optional Maximum value (inclusive) + * @property `minimum` - Optional Minimum value (inclusive) + * @property `exclusiveMaximum` - Optional Maximum value (exclusive) + * @property `exclusiveMinimum` - Optional Minimum value (exclusive) + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "number". + * + * ----- + * Examples + * ----- + * + * @example (basic number): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number" + * }; + * ``` + * + * @example (number with format and validation): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * format: "float", + * minimum: 0, + * maximum: 100 + * }; + * ``` + * + * @example (number with multipleOf): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * multipleOf: 0.5 + * }; + * ``` + * + * @example (number with exclusive bounds): + * ```ts + * const numberSchema: NumberSchema = { + * type: "number", + * exclusiveMinimum: 0, + * exclusiveMaximum: 100 + * }; + * ``` + */ +export interface NumberSchema extends Extension { + /** + * The type identifier for number schemas. + * Must be "number". + */ + type: "number"; + + /** + * The format of the number. + * See OpenAPI 3.2.0 Data Type Formats for further details. + * + * Example: `"float"`, `"double"` + */ + format?: string; + + /** + * The number must be a multiple of this value. + * Must be a positive number. + * + * Example: `0.5` + */ + multipleOf?: number; + + /** + * The maximum value of the number (inclusive). + * The number must be less than or equal to this value. + * + * Example: `100` + */ + maximum?: number; + + /** + * The minimum value of the number (inclusive). + * The number must be greater than or equal to this value. + * + * Example: `0` + */ + minimum?: number; + + /** + * The maximum value of the number (exclusive). + * The number must be less than this value. + * + * Example: `100` + */ + exclusiveMaximum?: number; + + /** + * The minimum value of the number (exclusive). + * The number must be greater than this value. + * + * Example: `0` + */ + exclusiveMinimum?: number; + + /** + * An array of allowed values for the number. + * The value must be one of the values in this array. + * + * Example: `[1, 2, 3, 4, 5]` + */ + enum?: number[]; + + /** + * A single allowed value for the number. + * The value must be exactly this value. + * + * Example: `42` + */ + const?: number; + + /** + * An array of example values for the number. + * These are for documentation purposes only. + * + * Example: `[1.5, 2.7, 3.14]` + */ + examples?: number[]; + + /** + * The default value for the number. + * This value will be used if no value is provided. + * + * Example: `0` + */ + default?: number; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"Price"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"The price of the item"` + */ + description?: string; +} diff --git a/3.2/data-types/object.ts b/3.2/data-types/object.ts new file mode 100644 index 0000000..3be86d6 --- /dev/null +++ b/3.2/data-types/object.ts @@ -0,0 +1,217 @@ +import type { Extension } from "../extensions"; +import type { Schema } from "../schema"; + +/** + * ----- + * Object Schema + * ----- + * + * A schema for object values. Includes object-specific validation properties + * that are only valid when `type: "object"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#data-types | OpenAPI 3.2.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "object"` - Required The type identifier for object schemas + * @property `properties` - Optional Map of property names to their schemas + * @property `required` - Optional Array of required property names + * @property `additionalProperties` - Optional Schema for additional properties + * @property `patternProperties` - Optional Map of regex patterns to schemas + * @property `propertyNames` - Optional Schema for property names + * @property `minProperties` - Optional Minimum number of properties + * @property `maxProperties` - Optional Maximum number of properties + * @property `dependentRequired` - Optional Map of property names to arrays of required properties + * @property `dependentSchemas` - Optional Map of property names to schemas + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "object". + * + * ----- + * Examples + * ----- + * + * @example (basic object): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * } + * }; + * ``` + * + * @example (object with required properties): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * }, + * required: ["name"] + * }; + * ``` + * + * @example (object with additionalProperties): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * properties: { + * name: { type: "string" } + * }, + * additionalProperties: { type: "string" } + * }; + * ``` + * + * @example (object with patternProperties): + * ```ts + * const objectSchema: ObjectSchema = { + * type: "object", + * patternProperties: { + * "^S_": { type: "string" } + * } + * }; + * ``` + */ +export interface ObjectSchema extends Extension { + /** + * The type identifier for object schemas. + * Must be "object". + */ + type: "object"; + + /** + * A map of property names to their schemas. + * Each property in the object must conform to its corresponding schema. + * + * Example: `{ name: { type: "string" }, age: { type: "number" } }` + */ + properties?: Record; + + /** + * An array of required property names. + * These properties must be present in the object. + * + * Example: `["name", "email"]` + */ + required?: string[]; + + /** + * The schema for additional properties not defined in properties. + * If false, no additional properties are allowed. + * If true, any additional properties are allowed. + * If a schema, additional properties must conform to this schema. + * + * Example: `{ type: "string" }` or `false` or `true` + */ + additionalProperties?: Schema | boolean; + + /** + * A map of regex patterns to schemas. + * Properties whose names match a pattern must conform to the corresponding schema. + * + * Example: `{ "^S_": { type: "string" } }` + */ + patternProperties?: Record; + + /** + * The schema for property names. + * All property names in the object must conform to this schema. + * + * Example: `{ type: "string", pattern: "^[A-Za-z][A-Za-z0-9]*$" }` + */ + propertyNames?: Schema; + + /** + * The minimum number of properties in the object. + * Must be a non-negative integer. + * + * Example: `1` + */ + minProperties?: number; + + /** + * The maximum number of properties in the object. + * Must be a non-negative integer. + * + * Example: `10` + */ + maxProperties?: number; + + /** + * A map of property names to arrays of required properties. + * If a property is present, the properties in its array must also be present. + * + * Example: `{ credit_card: ["billing_address"] }` + */ + dependentRequired?: Record; + + /** + * A map of property names to schemas. + * If a property is present, the object must conform to the corresponding schema. + * + * Example: `{ credit_card: { type: "object", properties: { number: { type: "string" } } } }` + */ + dependentSchemas?: Record; + + /** + * An array of allowed values for the object. + * The value must be one of the values in this array. + * + * Example: `[{ name: "John" }, { name: "Jane" }]` + */ + enum?: Record[]; + + /** + * A single allowed value for the object. + * The value must be exactly this value. + * + * Example: `{ name: "John" }` + */ + const?: Record; + + /** + * An array of example values for the object. + * These are for documentation purposes only. + * + * Example: `[{ name: "John", age: 30 }]` + */ + examples?: Record[]; + + /** + * The default value for the object. + * This value will be used if no value is provided. + * + * Example: `{}` + */ + default?: Record; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"A user object"` + */ + description?: string; +} diff --git a/3.2/data-types/reference.ts b/3.2/data-types/reference.ts new file mode 100644 index 0000000..9329847 --- /dev/null +++ b/3.2/data-types/reference.ts @@ -0,0 +1,70 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * Reference Schema + * ----- + * + * A schema that references another schema. When a schema contains `$ref`, + * no other sibling keys are allowed except `description` and extensions. + * This enforces the OpenAPI 3.2.0 rule that `$ref` is exclusive with other properties. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#reference-object | OpenAPI 3.2.0 Reference Object} | + * + * ----- + * Fields + * ----- + * + * @property `$ref` - Required A reference to a schema + * @property `description` - Optional A description of the referenced schema + * @property `x-${string}` - Specification Extensions + * + * @note + * When `$ref` is present, no other properties except `description` and extensions are allowed. + * + * ----- + * Examples + * ----- + * + * @example (simple reference): + * ```ts + * const reference: ReferenceSchema = { + * $ref: "#/components/schemas/User" + * }; + * ``` + * + * @example (reference with description): + * ```ts + * const reference: ReferenceSchema = { + * $ref: "#/components/schemas/User", + * description: "Reference to a user schema" + * }; + * ``` + * + * @example (reference with extension): + * ```ts + * const reference: ReferenceSchema = { + * $ref: "#/components/schemas/User", + * "x-custom": "value" + * }; + * ``` + */ +export interface ReferenceSchema extends Extension { + /** + * A reference to a schema. This MUST be in the form of a URI. + * When present, no other properties except `description` and extensions are allowed. + * + * Example: `"#/components/schemas/User"` + */ + $ref: string; + + /** + * A description of the referenced schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"Reference to a user schema"` + */ + description?: string; +} diff --git a/3.2/data-types/string.ts b/3.2/data-types/string.ts new file mode 100644 index 0000000..896a60c --- /dev/null +++ b/3.2/data-types/string.ts @@ -0,0 +1,158 @@ +import type { Extension } from "../extensions"; + +/** + * ----- + * String Schema + * ----- + * + * A schema for string values. Includes string-specific validation properties + * that are only valid when `type: "string"` is specified. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#data-types | OpenAPI 3.2.0 Data Types} | + * + * ----- + * Fields + * ----- + * + * @property `type: "string"` - Required The type identifier for string schemas + * @property `format` - Optional The format of the string + * @property `maxLength` - Optional Maximum length of the string + * @property `minLength` - Optional Minimum length of the string + * @property `pattern` - Optional Regular expression pattern + * @property `enum` - Optional Array of allowed values + * @property `const` - Optional Single allowed value + * @property `examples` - Optional Array of example values + * @property `default` - Optional Default value + * @property `title` - Optional Short title for the schema + * @property `description` - Optional Description of the schema + * @property `x-${string}` - Specification Extensions + * + * @note + * All validation properties are optional. The `type` field must be "string". + * + * ----- + * Examples + * ----- + * + * @example (basic string): + * ```ts + * const stringSchema: StringSchema = { + * type: "string" + * }; + * ``` + * + * @example (string with format and validation): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * format: "email", + * maxLength: 255, + * minLength: 5 + * }; + * ``` + * + * @example (string with enum): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * enum: ["active", "inactive", "pending"] + * }; + * ``` + * + * @example (string with pattern): + * ```ts + * const stringSchema: StringSchema = { + * type: "string", + * pattern: "^[A-Za-z0-9]+$" + * }; + * ``` + */ +export interface StringSchema extends Extension { + /** + * The type identifier for string schemas. + * Must be "string". + */ + type: "string"; + + /** + * The format of the string. + * See OpenAPI 3.2.0 Data Type Formats for further details. + * + * Example: `"email"`, `"date-time"`, `"uuid"` + */ + format?: string; + + /** + * The maximum length of the string. + * Must be a non-negative integer. + * + * Example: `255` + */ + maxLength?: number; + + /** + * The minimum length of the string. + * Must be a non-negative integer. + * + * Example: `1` + */ + minLength?: number; + + /** + * A regular expression pattern that the string must match. + * Should be a valid ECMA 262 regular expression. + * + * Example: `"^[A-Za-z0-9]+$"` + */ + pattern?: string; + + /** + * An array of allowed values for the string. + * The value must be one of the values in this array. + * + * Example: `["active", "inactive", "pending"]` + */ + enum?: string[]; + + /** + * A single allowed value for the string. + * The value must be exactly this value. + * + * Example: `"active"` + */ + const?: string; + + /** + * An array of example values for the string. + * These are for documentation purposes only. + * + * Example: `["example@email.com", "test@domain.com"]` + */ + examples?: string[]; + + /** + * The default value for the string. + * This value will be used if no value is provided. + * + * Example: `"default"` + */ + default?: string; + + /** + * A short title for the schema. + * This is for documentation purposes only. + * + * Example: `"User Email"` + */ + title?: string; + + /** + * A description of the schema. + * CommonMark syntax MAY be used for rich text representation. + * + * Example: `"The email address of the user"` + */ + description?: string; +} diff --git a/3.2/extensions.ts b/3.2/extensions.ts new file mode 100644 index 0000000..4cb793c --- /dev/null +++ b/3.2/extensions.ts @@ -0,0 +1,62 @@ +/** + * ----- + * Extension Interface + * ----- + * + * The Extension interface provides a way to add custom properties to OpenAPI objects + * using the `x-` prefix. This allows for specification extensions that are not part + * of the core OpenAPI specification but can be used by tools and implementations + * to provide additional functionality. + * + * Specification Extensions (`x-*`) are always allowed on OpenAPI objects. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#specification-extensions | OpenAPI 3.2.0 Specification Extensions} | + * + * ----- + * Fields + * ----- + * + * @property `x-${string}` - Specification Extensions + * + * @note + * All extension properties must start with `x-` and can contain any valid JSON value. + * + * ----- + * Examples + * ----- + * + * @example (simple extension): + * ```ts + * const extended: Extension = { + * "x-custom-property": "custom value", + * "x-internal-id": 123 + * }; + * ``` + * + * @example (complex extension): + * ```ts + * const extended: Extension = { + * "x-codegen-settings": { + * "packageName": "com.example.api", + * "generateTests": true + * }, + * "x-rate-limit": { + * "requests": 1000, + * "window": "1h" + * } + * }; + * ``` + */ +export interface Extension { + /** + * Specification Extensions allow adding custom properties to OpenAPI objects. + * All extension properties must start with `x-` and can contain any valid JSON value. + * + * @example "x-custom-property" + * @example "x-internal-id" + * @example "x-codegen-settings" + */ + [key: `x-${string}`]: unknown; +} diff --git a/3.2/externalDocs.ts b/3.2/externalDocs.ts new file mode 100644 index 0000000..a945e7e --- /dev/null +++ b/3.2/externalDocs.ts @@ -0,0 +1,62 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * External Documentation Object + * ----- + * + * Allows referencing an external resource for extended documentation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#external-documentation-object | OpenAPI 3.2.0 External Documentation Object} | + * + * ----- + * Fields + * ----- + * + * @property `description` - Optional A short description of the target documentation + * @property `url` - Required The URL for the target documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `url` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple external docs): + * ```ts + * const externalDocs: ExternalDocumentation = { + * url: "https://example.com/docs" + * }; + * ``` + * + * @example (external docs with description): + * ```ts + * const externalDocs: ExternalDocumentation = { + * description: "Find out more about our API", + * url: "https://example.com/docs" + * }; + * ``` + */ +export interface ExternalDocumentation extends Extension { + /** + * A short description of the target documentation. CommonMark syntax MAY be used + * for rich text representation. + * + * @example "Find out more about our API" + * @example "Additional documentation for this endpoint" + */ + description?: string; + + /** + * The URL for the target documentation. This field is required and MUST be in the + * format of a URL. + * + * @example "https://example.com/docs" + * @example "https://docs.example.com/api" + */ + url: string; +} diff --git a/3.2/index.ts b/3.2/index.ts new file mode 100644 index 0000000..c2e1040 --- /dev/null +++ b/3.2/index.ts @@ -0,0 +1,60 @@ +/** + * @fileoverview OpenAPI 3.2.0 TypeScript Type Definitions + * + * This module provides comprehensive TypeScript type definitions for OpenAPI 3.2.0 specifications. + * All types are fully documented with JSDoc comments and include links to the official OpenAPI + * specification documentation. + * + * @see {@link https://spec.openapis.org/oas/v3.2.0.html | OpenAPI 3.2.0 Specification} + * + * @version 3.2.0 + * @since 1.0.0 + */ + +// Component types +export type { Components } from "./components"; +// Re-export data-types for convenience +export type { + ArraySchema as DataTypeArraySchema, + BooleanSchema as DataTypeBooleanSchema, + CompositionSchema as DataTypeCompositionSchema, + IntegerSchema as DataTypeIntegerSchema, + NumberSchema as DataTypeNumberSchema, + ObjectSchema as DataTypeObjectSchema, + ReferenceSchema as DataTypeReferenceSchema, + StringSchema as DataTypeStringSchema, +} from "./data-types"; +// Core OpenAPI types +export type { Extension } from "./extensions"; +export type { ExternalDocumentation } from "./externalDocs"; + +// Info and metadata types +export type { Contact, Info, License } from "./info"; +export type { OAuthFlow, OAuthFlows } from "./oauth"; +// Path types +export type { PathItemObject, Paths } from "./paths"; +export type { Reference } from "./references"; +// Schema types +export type { + ArraySchema, + BooleanSchema, + CompositionSchema, + Discriminator, + IntegerSchema, + NumberSchema, + ObjectSchema, + ReferenceSchema, + Schema, + StringSchema, +} from "./schema"; +// Security types +export type { SecurityRequirement } from "./security"; +// Server types +export type { Server, ServerVariable } from "./servers"; +// Specification type +export type { Specification } from "./spec"; +// Tag types +export type { Tag } from "./tags"; +// Webhook types +export type { Webhooks } from "./webhooks"; +export type { XML } from "./xml"; diff --git a/3.2/info.ts b/3.2/info.ts new file mode 100644 index 0000000..97c5f05 --- /dev/null +++ b/3.2/info.ts @@ -0,0 +1,350 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Info Object + * ----- + * + * The object provides metadata about the API. The metadata MAY be used by tooling + * as required. The object may be extended with Specification Extensions. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object} | + * + * ----- + * Fields + * ----- + * + * @property `title` - Required The title of the API + * @property `summary` - Optional A short summary of the API + * @property `description` - Optional A description of the API + * @property `termsOfService` - Optional A URL to the Terms of Service for the API + * @property `contact` - Optional The contact information for the exposed API + * @property `license` - Optional The license information for the exposed API + * @property `version` - Required The version of the OpenAPI document + * @property `x-${string}` - Specification Extensions + * + * @note + * The `title` and `version` fields are required. + * + * ----- + * Examples + * ----- + * + * @example (minimal info): + * ```ts + * const info: Info = { + * title: "Pet Store API", + * version: "1.0.0" + * }; + * ``` + * + * @example (complete info): + * ```ts + * const info: Info = { + * title: "Pet Store API", + * summary: "A sample API that uses a petstore as an example", + * description: "This is a sample server Petstore server.", + * termsOfService: "http://example.com/terms/", + * contact: { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }, + * license: { + * name: "Apache 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0.html" + * }, + * version: "1.0.0" + * }; + * ``` + */ +export interface Info extends Extension { + /** + * The title of the API. + * This field is required and should be descriptive of the API. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - title} | + * + * @property `title` - Required The title of the API + * + * @example "Pet Store API" + */ + title: string; + + /** + * A short summary of the API. + * This should be a brief description of what the API does. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - summary} | + * + * @property `summary` - Optional A short summary of the API + * + * @example "A sample API that uses a petstore as an example" + */ + summary?: string; + + /** + * A description of the API. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - description} | + * + * @property `description` - Optional A description of the API + * + * @example "This is a sample server Petstore server." + */ + description?: string; + + /** + * A URL to the Terms of Service for the API. + * This MUST be in the format of a URL. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - termsOfService} | + * + * @property `termsOfService` - Optional A URL to the Terms of Service for the API + * + * @example "http://example.com/terms/" + */ + termsOfService?: string; + + /** + * The contact information for the exposed API. + * This object contains contact details for the API. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - contact} | + * + * @property `contact` - Optional The contact information for the exposed API + * + * @example { name: "API Support", email: "support@example.com" } + */ + contact?: Contact; + + /** + * The license information for the exposed API. + * This object contains license details for the API. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - license} | + * + * @property `license` - Optional The license information for the exposed API + * + * @example { name: "Apache 2.0", url: "https://www.apache.org/licenses/LICENSE-2.0.html" } + */ + license?: License; + + /** + * The version of the OpenAPI document. + * This field is required and should follow semantic versioning. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - version} | + * + * @property `version` - Required The version of the OpenAPI document + * + * @example "1.0.0" + */ + version: string; +} + +/** + * ----- + * Contact Object + * ----- + * + * The Contact Object provides contact information for the exposed API. + * It appears in the OpenAPI and Swagger specifications from v2.0 through v3.2.x. + * + * Specification Extensions (`x-*`) are always allowed. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Optional The identifying name of the contact person/organization. + * @property `url` - Optional A URL pointing to the contact information. + * @property `email` - Optional The email address of the contact person/organization. + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. + * + * ----- + * Examples + * ----- + * + * @example (full contact object): + * ```ts + * const contact: Contact = { + * name: "API Support", + * url: "http://www.acme.com/support", + * email: "support@acme.com" + * }; + * ``` + * + * @example (just name + email): + * ```ts + * const contact: Contact = { + * name: "Jane Doe", + * email: "jane.doe@acme.com" + * }; + * ``` + * + * @example (with extension): + * ```ts + * const contact: Contact = { + * name: "Internal API Team", + * email: "api-team@acme.com", + * "x-slack": "#api-support" + * }; + * ``` + */ +export interface Contact extends Extension { + /** + * The identifying name of the contact person/organization. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact Object - name} | + * + * @property `name` - Optional The identifying name of the contact person/organization + * + * @example "API Support" + * @example "John Doe" + */ + name?: string; + + /** + * The URL pointing to the contact information. + * MUST be in the format of a URL. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact Object - url} | + * + * @property `url` - Optional A URL pointing to the contact information + * + * @example "http://www.acme.com/support" + * @example "https://example.com/contact" + */ + url?: string; + + /** + * The email address of the contact person/organization. + * MUST be in the format of an email address. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact Object - email} | + * + * @property `email` - Optional The email address of the contact person/organization + * + * @example "support@acme.com" + * @example "contact@example.com" + */ + email?: string; +} + +/** + * ----- + * License Object + * ----- + * + * The License Object provides license information for the exposed API. + * It appears in the OpenAPI and Swagger specifications from v2.0 through v3.2.x. + * + * Specification Extensions (`x-*`) are always allowed. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#license-object | OpenAPI 3.2.0 License} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The license name used for the API. + * @property `url` - Optional A URL to the license used for the API. + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` field is required. + * + * ----- + * Examples + * ----- + * + * @example (license with name only): + * ```ts + * const license: License = { + * name: "Apache 2.0" + * }; + * ``` + * + * @example (license with name and URL): + * ```ts + * const license: License = { + * name: "Apache 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0.html" + * }; + * ``` + * + * @example (license with extension): + * ```ts + * const license: License = { + * name: "MIT", + * url: "https://opensource.org/licenses/MIT", + * "x-spdx-id": "MIT" + * }; + * ``` + */ +export interface License extends Extension { + /** + * The license name used for the API. + * This field is required. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#license-object | OpenAPI 3.2.0 License Object - name} | + * + * @property `name` - Required The license name used for the API + * + * @example "Apache 2.0" + * @example "MIT" + * @example "Proprietary License" + */ + name: string; + + /** + * A URL to the license used for the API. + * MUST be in the format of a URL. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#license-object | OpenAPI 3.2.0 License Object - url} | + * + * @property `url` - Optional A URL to the license used for the API + * + * @example "https://www.apache.org/licenses/LICENSE-2.0.html" + * @example "https://opensource.org/licenses/MIT" + * @example "https://example.com/licenses/proprietary-1.0" + */ + url?: string; +} diff --git a/3.2/oauth.ts b/3.2/oauth.ts new file mode 100644 index 0000000..cd8dfd2 --- /dev/null +++ b/3.2/oauth.ts @@ -0,0 +1,223 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * OAuth Flow Object + * ----- + * + * Configuration details for a supported OAuth Flow. + * This object describes the OAuth flow configuration for a specific OAuth flow type. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#oauth-flow-object | OpenAPI 3.2.0 OAuth Flow Object} | + * + * ----- + * Fields + * ----- + * + * @property `authorizationUrl` - Optional The authorization URL to be used for this flow + * @property `tokenUrl` - Optional The token URL to be used for this flow + * @property `refreshUrl` - Optional The URL to be used for obtaining refresh tokens + * @property `scopes` - Required A map between the scope name and a short description + * @property `oauth2MetadataUrl` - Optional The URL to be used for OAuth 2.0 metadata + * @property `x-${string}` - Specification Extensions + * + * @note + * The `scopes` field is required and must contain at least one scope. + * The `authorizationUrl` and `tokenUrl` fields are required for certain flow types. + * + * ----- + * Examples + * ----- + * + * @example (authorization code flow): + * ```ts + * const oauthFlow: OAuthFlow = { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access to user data", + * "write": "Write access to user data" + * } + * }; + * ``` + * + * @example (client credentials flow): + * ```ts + * const oauthFlow: OAuthFlow = { + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "api": "Full API access" + * } + * }; + * ``` + * + * @example (implicit flow): + * ```ts + * const oauthFlow: OAuthFlow = { + * authorizationUrl: "https://example.com/oauth/authorize", + * scopes: { + * "read": "Read access to user data" + * } + * }; + * ``` + */ +export interface OAuthFlow extends Extension { + /** + * The authorization URL to be used for this flow. + * This MUST be in the form of a URL. + * + * Example: `"https://example.com/oauth/authorize"` + */ + authorizationUrl?: string; + + /** + * The token URL to be used for this flow. + * This MUST be in the form of a URL. + * + * Example: `"https://example.com/oauth/token"` + */ + tokenUrl?: string; + + /** + * The URL to be used for obtaining refresh tokens. + * This MUST be in the form of a URL. + * + * Example: `"https://example.com/oauth/refresh"` + */ + refreshUrl?: string; + + /** + * A map between the scope name and a short description for it. + * The map MAY be empty. + * + * Example: `{ "read": "Read access to user data", "write": "Write access to user data" }` + */ + scopes: Record; + + /** + * The URL to be used for OAuth 2.0 metadata. + * This MUST be in the form of a URL. + * + * Example: `"https://example.com/.well-known/oauth-authorization-server"` + */ + oauth2MetadataUrl?: string; +} + +/** + * ----- + * OAuth Flows Object + * ----- + * + * Allows configuration of the supported OAuth Flows. + * This object describes the OAuth flows that are available for this API. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#oauth-flows-object | OpenAPI 3.2.0 OAuth Flows Object} | + * + * ----- + * Fields + * ----- + * + * @property `implicit` - Optional Configuration for the OAuth Implicit flow + * @property `password` - Optional Configuration for the OAuth Resource Owner Password flow + * @property `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow + * @property `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow + * @property `deviceAuthorization` - Optional Configuration for the OAuth Device Authorization flow + * @property `x-${string}` - Specification Extensions + * + * @note + * At least one flow must be specified. The flows are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (authorization code flow): + * ```ts + * const oauthFlows: OAuthFlows = { + * authorizationCode: { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access to user data", + * "write": "Write access to user data" + * } + * } + * }; + * ``` + * + * @example (client credentials flow): + * ```ts + * const oauthFlows: OAuthFlows = { + * clientCredentials: { + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "api": "Full API access" + * } + * } + * }; + * ``` + * + * @example (multiple flows): + * ```ts + * const oauthFlows: OAuthFlows = { + * authorizationCode: { + * authorizationUrl: "https://example.com/oauth/authorize", + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "read": "Read access to user data" + * } + * }, + * clientCredentials: { + * tokenUrl: "https://example.com/oauth/token", + * scopes: { + * "api": "Full API access" + * } + * } + * }; + * ``` + */ +export interface OAuthFlows extends Extension { + /** + * Configuration for the OAuth Implicit flow. + * This flow is deprecated in OAuth 2.1. + * + * Example: `{ authorizationUrl: "https://example.com/oauth/authorize", scopes: { "read": "Read access" } }` + */ + implicit?: OAuthFlow; + + /** + * Configuration for the OAuth Resource Owner Password flow. + * This flow is deprecated in OAuth 2.1. + * + * Example: `{ tokenUrl: "https://example.com/oauth/token", scopes: { "read": "Read access" } }` + */ + password?: OAuthFlow; + + /** + * Configuration for the OAuth Client Credentials flow. + * This flow is suitable for machine-to-machine authentication. + * + * Example: `{ tokenUrl: "https://example.com/oauth/token", scopes: { "api": "Full API access" } }` + */ + clientCredentials?: OAuthFlow; + + /** + * Configuration for the OAuth Authorization Code flow. + * This is the recommended flow for web applications. + * + * Example: `{ authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { "read": "Read access" } }` + */ + authorizationCode?: OAuthFlow; + + /** + * Configuration for the OAuth Device Authorization flow. + * This flow is suitable for devices with limited input capabilities. + * + * Example: `{ deviceCodeUrl: "https://example.com/oauth/device", tokenUrl: "https://example.com/oauth/token", scopes: { "read": "Read access" } }` + */ + deviceAuthorization?: OAuthFlow; +} diff --git a/3.2/paths.ts b/3.2/paths.ts new file mode 100644 index 0000000..5f335e8 --- /dev/null +++ b/3.2/paths.ts @@ -0,0 +1,716 @@ +import type { Callback, Example, MediaType, RequestBody } from "./components"; +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +import type { Reference } from "./references"; +import type { Schema } from "./schema"; +import type { SecurityRequirement } from "./security"; +import type { Server } from "./servers"; +import type { ResponsesMap } from "./status"; + +/** + * ----- + * Path Item Object + * ----- + * + * Describes the operations available on a single path. A Path Item MAY be empty, + * due to ACL constraints. The path itself is still exposed to the documentation + * viewer but they will not know which operations and parameters are available. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object} | + * + * ----- + * Fields + * ----- + * + * @property `summary` - Optional An optional, string summary, intended to apply to all operations in this path + * @property `description` - Optional An optional, string description, intended to apply to all operations in this path + * @property `get` - Optional A definition of a GET operation on this path + * @property `put` - Optional A definition of a PUT operation on this path + * @property `post` - Optional A definition of a POST operation on this path + * @property `delete` - Optional A definition of a DELETE operation on this path + * @property `options` - Optional A definition of an OPTIONS operation on this path + * @property `head` - Optional A definition of a HEAD operation on this path + * @property `patch` - Optional A definition of a PATCH operation on this path + * @property `trace` - Optional A definition of a TRACE operation on this path + * @property `servers` - Optional An alternative server array to service all operations in this path + * @property `parameters` - Optional A list of parameters that are applicable for all the operations described under this path + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. The HTTP methods are mutually exclusive. + * + * ----- + * Examples + * ----- + * + * @example (simple path item): + * ```ts + * const pathItem: PathItemObject = { + * "get": { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * } + * }; + * ``` + */ +export interface PathItemObject extends Extension { + /** + * An optional, string summary, intended to apply to all operations in this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - summary} | + * + * @property `summary` - Optional An optional, string summary, intended to apply to all operations in this path + * + * @example "Pet operations" + * @example "User management" + */ + summary?: string; + + /** + * An optional, string description, intended to apply to all operations in this path. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - description} | + * + * @property `description` - Optional An optional, string description, intended to apply to all operations in this path + * + * @example "Operations related to pet management" + * @example "All user-related operations" + */ + description?: string; + + /** + * A definition of a GET operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - get} | + * + * @property `get` - Optional A definition of a GET operation on this path + */ + get?: Operation; + + /** + * A definition of a PUT operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - put} | + * + * @property `put` - Optional A definition of a PUT operation on this path + */ + put?: Operation; + + /** + * A definition of a POST operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - post} | + * + * @property `post` - Optional A definition of a POST operation on this path + */ + post?: Operation; + + /** + * A definition of a DELETE operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - delete} | + * + * @property `delete` - Optional A definition of a DELETE operation on this path + */ + delete?: Operation; + + /** + * A definition of an OPTIONS operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - options} | + * + * @property `options` - Optional A definition of an OPTIONS operation on this path + */ + options?: Operation; + + /** + * A definition of a HEAD operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - head} | + * + * @property `head` - Optional A definition of a HEAD operation on this path + */ + head?: Operation; + + /** + * A definition of a PATCH operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - patch} | + * + * @property `patch` - Optional A definition of a PATCH operation on this path + */ + patch?: Operation; + + /** + * A definition of a TRACE operation on this path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - trace} | + * + * @property `trace` - Optional A definition of a TRACE operation on this path + */ + trace?: Operation; + + /** + * An alternative server array to service all operations in this path. + * If an alternative server object is specified at the Path Item Object level, + * it will override the server object defined at the root level. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - servers} | + * + * @property `servers` - Optional An alternative server array to service all operations in this path + */ + servers?: Server[]; + + /** + * A list of parameters that are applicable for all the operations described under this path. + * These parameters can be overridden at the operation level, but cannot be removed there. + * The list MUST NOT include duplicated parameters. A unique parameter is defined by a + * combination of a name and location. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#path-item-object | OpenAPI 3.2.0 Path Item Object - parameters} | + * + * @property `parameters` - Optional A list of parameters that are applicable for all the operations described under this path + */ + parameters?: Parameter[]; +} + +/** + * ----- + * Operation Object + * ----- + * + * Describes a single API operation on a path. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object} | + * + * ----- + * Fields + * ----- + * + * @property `tags` - Optional A list of tags for API documentation control + * @property `summary` - Optional A short summary of what the operation does + * @property `description` - Optional A verbose explanation of the operation behavior + * @property `externalDocs` - Optional Additional external documentation for this operation + * @property `operationId` - Optional Unique string used to identify the operation + * @property `parameters` - Optional A list of parameters that are applicable for this operation + * @property `requestBody` - Optional The request body applicable for this operation + * @property `responses` - Optional The list of possible responses as they are returned from executing this operation + * @property `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation + * @property `deprecated` - Optional Declares this operation to be deprecated + * @property `security` - Optional A declaration of which security mechanisms can be used for this operation + * @property `servers` - Optional An alternative server array to service this operation + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. The `responses` field is required for all operations. + * + * ----- + * Examples + * ----- + * + * @example (basic operation): + * ```ts + * const operation: Operation = { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * }; + * ``` + */ +export interface Operation extends Extension { + /** + * A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - tags} | + * + * @property `tags` - Optional A list of tags for API documentation control + * + * @example ["pets", "list"] + * @example ["users", "authentication"] + */ + tags?: string[]; + + /** + * A short summary of what the operation does. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - summary} | + * + * @property `summary` - Optional A short summary of what the operation does + * + * @example "List all pets" + * @example "Create a new user" + */ + summary?: string; + + /** + * A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - description} | + * + * @property `description` - Optional A verbose explanation of the operation behavior + * + * @example "Returns a list of all pets in the system" + * @example "Creates a new user account with the provided information" + */ + description?: string; + + /** + * Additional external documentation for this operation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - externalDocs} | + * + * @property `externalDocs` - Optional Additional external documentation for this operation + */ + externalDocs?: ExternalDocumentation; + + /** + * Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - operationId} | + * + * @property `operationId` - Optional Unique string used to identify the operation + * + * @example "listPets" + * @example "createUser" + */ + operationId?: string; + + /** + * A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item level, the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - parameters} | + * + * @property `parameters` - Optional A list of parameters that are applicable for this operation + */ + parameters?: Parameter[]; + + /** + * The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - requestBody} | + * + * @property `requestBody` - Optional The request body applicable for this operation + */ + requestBody?: RequestBody; + + /** + * The list of possible responses as they are returned from executing this operation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - responses} | + * + * @property `responses` - Optional The list of possible responses as they are returned from executing this operation + */ + responses?: ResponsesMap; + + /** + * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - callbacks} | + * + * @property `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation + */ + callbacks?: Record; + + /** + * Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - deprecated} | + * + * @property `deprecated` - Optional Declares this operation to be deprecated + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level security. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - security} | + * + * @property `security` - Optional A declaration of which security mechanisms can be used for this operation + */ + security?: SecurityRequirement[]; + + /** + * An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#operation-object | OpenAPI 3.2.0 Operation Object - servers} | + * + * @property `servers` - Optional An alternative server array to service this operation + */ + servers?: Server[]; +} + +/** + * ----- + * Parameter Object + * ----- + * + * Describes a single operation parameter. + * A unique parameter is defined by a combination of a name and location. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The name of the parameter + * @property `in` - Required The location of the parameter + * @property `description` - Optional A brief description of the parameter + * @property `required` - Optional Determines whether this parameter is mandatory + * @property `deprecated` - Optional Specifies that a parameter is deprecated + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters + * @property `style` - Optional Describes how the parameter value will be serialized + * @property `explode` - Optional When this is true, parameter values generate separate parameters + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * @property `schema` - Optional The schema defining the type used for the parameter + * @property `example` - Optional Example of the media type + * @property `examples` - Optional Examples of the media type + * @property `content` - Optional A map containing the representations for the parameter + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` and `in` fields are required. A parameter MUST contain either a `schema` property, or a `content` property, but not both. + * + * ----- + * Examples + * ----- + * + * @example (path parameter): + * ```ts + * const parameter: Parameter = { + * name: "id", + * in: "path", + * required: true, + * description: "User ID", + * schema: { type: "string" } + * }; + * ``` + * + * @example (query parameter): + * ```ts + * const parameter: Parameter = { + * name: "limit", + * in: "query", + * description: "Number of items to return", + * schema: { type: "integer", minimum: 1, maximum: 100 } + * }; + * ``` + */ +export interface Parameter extends Extension { + /** + * The name of the parameter. Parameter names are case sensitive. + * - If in is "path", the name field MUST correspond to the associated path segment + * - If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored + * - For all other cases, the name corresponds to the parameter name used by the in property + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - name} | + * + * @property `name` - Required The name of the parameter + * + * @example "id" + * @example "limit" + * @example "user" + */ + name: string; + + /** + * The location of the parameter. Possible values are "query", "header", "path" or "cookie". + * + * - **query**: Parameters that are appended to the URL + * - **header**: Custom headers that are expected as part of the request + * - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL + * - **cookie**: Used to pass a specific cookie value to the API + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - in} | + * + * @property `in` - Required The location of the parameter + * + * @example "query" + * @example "path" + * @example "header" + * @example "cookie" + */ + in: "query" | "header" | "path" | "cookie"; + + /** + * A brief description of the parameter. This could contain examples of use. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - description} | + * + * @property `description` - Optional A brief description of the parameter + * + * @example "User ID to retrieve" + * @example "Number of items to return" + */ + description?: string; + + /** + * Determines whether this parameter is mandatory. If the parameter location is "path", + * this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be + * included and its default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - required} | + * + * @property `required` - Optional Determines whether this parameter is mandatory + * + * @example true + * @example false + */ + required?: boolean; + + /** + * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - deprecated} | + * + * @property `deprecated` - Optional Specifies that a parameter is deprecated and SHOULD be transitioned out of usage + * + * @example true + * @example false + */ + deprecated?: boolean; + + /** + * Sets the ability to pass empty-valued parameters. This is valid only for query + * parameters and allows sending a parameter with an empty value. Default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - allowEmptyValue} | + * + * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters + * + * @example true + * @example false + */ + allowEmptyValue?: boolean; + + /** + * Describes how the parameter value will be serialized depending on the type of the parameter value. + * Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - style} | + * + * @property `style` - Optional Describes how the parameter value will be serialized + * + * @example "form" + * @example "simple" + * @example "matrix" + * @example "label" + * @example "spaceDelimited" + * @example "pipeDelimited" + * @example "deepObject" + */ + style?: + | "matrix" + | "label" + | "form" + | "simple" + | "spaceDelimited" + | "pipeDelimited" + | "deepObject"; + + /** + * When this is true, parameter values of type array or object generate separate parameters + * for each value of the array or key-value pair of the map. For other types of parameters + * this property has no effect. When style is form, the default value is true. + * For all other styles, the default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - explode} | + * + * @property `explode` - Optional When this is true, parameter values of type array or object generate separate parameters + * + * @example true + * @example false + */ + explode?: boolean; + + /** + * Determines whether the parameter value SHOULD allow reserved characters, as defined by + * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only + * applies to parameters with an in value of query. The default value is false. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - allowReserved} | + * + * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters + * + * @example true + * @example false + */ + allowReserved?: boolean; + + /** + * The schema defining the type used for the parameter. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - schema} | + * + * @property `schema` - Optional The schema defining the type used for the parameter + * + * @example { type: "string" } + * @example { type: "integer", minimum: 1, maximum: 100 } + */ + schema?: Schema; + + /** + * Example of the media type. The example SHOULD match the specified schema and encoding + * properties if present. The example object is mutually exclusive of the examples object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - example} | + * + * @property `example` - Optional Example of the media type + * + * @example "example-value" + * @example 42 + */ + example?: unknown; + + /** + * Examples of the media type. Each example SHOULD contain a value in the correct format + * as specified in the parameter encoding. The examples object is mutually exclusive of + * the example object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - examples} | + * + * @property `examples` - Optional Examples of the media type + * + * @example { "user1": { summary: "A user example", value: "user123" } } + */ + examples?: Record; + + /** + * A map containing the representations for the parameter. The key is the media type + * and the value describes it. The map MUST only contain one entry. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#parameter-object | OpenAPI 3.2.0 Parameter Object - content} | + * + * @property `content` - Optional A map containing the representations for the parameter + * + * @example { "application/json": { schema: { type: "object" } } } + */ + content?: Record; +} + +/** + * ----- + * Paths Object + * ----- + * + * Holds the relative paths to the individual endpoints and their operations. + * The path is appended to the URL from the Server Object in order to construct + * the full URL. The Paths may be empty, due to ACL constraints. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#paths-object | OpenAPI 3.2.0 Paths Object} | + * + * ----- + * Examples + * ----- + * + * @example (simple paths): + * ```ts + * const paths: Paths = { + * "/pets": { + * "get": { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * } + * } + * }; + * ``` + */ +export type Paths = Record; diff --git a/3.2/references.ts b/3.2/references.ts new file mode 100644 index 0000000..15cae52 --- /dev/null +++ b/3.2/references.ts @@ -0,0 +1,84 @@ +/** + * ----- + * Reference Object + * ----- + * + * A simple object to allow referencing other components in the specification, + * internally and externally. The Reference Object is a special JSON object + * that allows you to reference other parts of the OpenAPI specification. + * + * The `$ref` keyword is used to reference other components, and when present, + * the Reference Object is the only property that should be present (except + * for `description` and specification extensions). + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#reference-object | OpenAPI 3.2.0 Reference Object} | + * + * ----- + * Fields + * ----- + * + * @property `$ref` - Required The reference string + * @property `description` - Optional A description of the referenced object + * @property `summary` - Optional A short summary of the referenced object + * @property `x-${string}` - Specification Extensions + * + * @note + * The `$ref` field is required and must be a valid JSON Reference. + * + * ----- + * Examples + * ----- + * + * @example (internal reference): + * ```ts + * const reference: Reference = { + * "$ref": "#/components/schemas/User" + * }; + * ``` + * + * @example (external reference): + * ```ts + * const reference: Reference = { + * "$ref": "https://example.com/schemas/User.json" + * }; + * ``` + * + * @example (reference with description): + * ```ts + * const reference: Reference = { + * "$ref": "#/components/schemas/User", + * "description": "A user object containing user information" + * }; + * ``` + */ +export interface Reference { + /** + * The reference string. This field is required and must be a valid JSON Reference. + * It can reference internal components using `#/` or external resources using URLs. + * + * @example "#/components/schemas/User" + * @example "#/components/responses/NotFound" + * @example "https://example.com/schemas/User.json" + */ + $ref: string; + + /** + * A description of the referenced object. This can be used to provide + * additional context about what the referenced object represents. + * + * @example "A user object containing user information" + * @example "Standard error response for not found resources" + */ + description?: string; + + /** + * A short summary of the referenced object. This can be used to provide + * a brief overview of what the referenced object represents. + * + * @example "User schema" + * @example "Not found response" + */ + summary?: string; +} diff --git a/3.2/schema.ts b/3.2/schema.ts new file mode 100644 index 0000000..6c90bc8 --- /dev/null +++ b/3.2/schema.ts @@ -0,0 +1,238 @@ +import type { + ArraySchema, + BooleanSchema, + CompositionSchema, + IntegerSchema, + NumberSchema, + ObjectSchema, + ReferenceSchema, + StringSchema, +} from "./data-types"; +import type { Extension } from "./extensions"; + +/** + * ----- + * Discriminator Object + * ----- + * + * The Discriminator Object is used to aid in serialization, deserialization, and validation. + * It can be used to differentiate between other schemas which may satisfy the payload description. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#discriminator-object | OpenAPI 3.2.0 Discriminator Object} | + * + * ----- + * Fields + * ----- + * + * @property `propertyName` - Required The name of the property in the payload that will hold the discriminator value + * @property `mapping` - Optional An object to hold mappings between payload values and schema names or references + * @property `x-${string}` - Specification Extensions + * + * @note + * The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. + * + * ----- + * Examples + * ----- + * + * @example (basic discriminator): + * ```ts + * const discriminator: Discriminator = { + * propertyName: "petType" + * }; + * ``` + * + * @example (discriminator with mapping): + * ```ts + * const discriminator: Discriminator = { + * propertyName: "petType", + * mapping: { + * dog: "#/components/schemas/Dog", + * cat: "#/components/schemas/Cat" + * } + * }; + * ``` + */ +export interface Discriminator extends Extension { + /** + * The name of the property in the payload that will hold the discriminator value. + * This property must be present in the payload. + * + * Example: `"petType"` + */ + propertyName: string; + + /** + * An object to hold mappings between payload values and schema names or references. + * If not provided, the schema name will be used as the discriminator value. + * + * Example: `{ dog: "#/components/schemas/Dog", cat: "#/components/schemas/Cat" }` + */ + mapping?: Record; +} + +/** + * ----- + * Schema Object + * ----- + * + * The Schema Object allows the definition of input and output data types. These types + * can be objects, but also primitives and arrays. This object is an extended subset + * of the JSON Schema Specification Draft 2020-12. + * + * The Schema Object is a discriminated union that enforces mutual-exclusion and + * co-occurrence rules as specified in the OpenAPI 3.2.0 specification. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#schema-object | OpenAPI 3.2.0 Schema Object} | + * + * ----- + * Schema Types + * ----- + * + * The Schema union includes the following types: + * + * **Reference Schema:** + * @property `$ref` - A reference to a schema (exclusive with other properties) + * @property `description` - A description of the referenced schema + * + * **String Schema:** + * @property `type: "string"` - The type identifier for string schemas + * @property `format` - The format of the string (email, date, uuid, etc.) + * @property `maxLength` - The maximum length of the string + * @property `minLength` - The minimum length of the string + * @property `pattern` - A regular expression pattern the string must match + * @property `enum` - An enumeration of string values + * @property `const` - A constant string value + * + * **Number Schema:** + * @property `type: "number"` - The type identifier for number schemas + * @property `format` - The format of the number (float, double) + * @property `multipleOf` - A number that must be a multiple of this value + * @property `maximum` - The maximum value (inclusive) + * @property `exclusiveMaximum` - The maximum value (exclusive) + * @property `minimum` - The minimum value (inclusive) + * @property `exclusiveMinimum` - The minimum value (exclusive) + * @property `enum` - An enumeration of number values + * @property `const` - A constant number value + * + * **Integer Schema:** + * @property `type: "integer"` - The type identifier for integer schemas + * @property `format` - The format of the integer (int32, int64) + * @property `multipleOf` - An integer that must be a multiple of this value + * @property `maximum` - The maximum value (inclusive) + * @property `exclusiveMaximum` - The maximum value (exclusive) + * @property `minimum` - The minimum value (inclusive) + * @property `exclusiveMinimum` - The minimum value (exclusive) + * @property `enum` - An enumeration of integer values + * @property `const` - A constant integer value + * + * **Boolean Schema:** + * @property `type: "boolean"` - The type identifier for boolean schemas + * @property `enum` - An enumeration of boolean values + * @property `const` - A constant boolean value + * + * **Array Schema:** + * @property `type: "array"` - The type identifier for array schemas + * @property `items` - The schema for array items + * @property `prefixItems` - The schema for array items at specific positions + * @property `contains` - The schema that array must contain at least one item matching + * @property `minContains` - The minimum number of items that must match contains + * @property `maxContains` - The maximum number of items that must match contains + * @property `minItems` - The minimum number of items in the array + * @property `maxItems` - The maximum number of items in the array + * @property `uniqueItems` - Whether array items must be unique + * + * **Object Schema:** + * @property `type: "object"` - The type identifier for object schemas + * @property `properties` - A map of property names to their schemas + * @property `required` - An array of required property names + * @property `additionalProperties` - The schema for additional properties + * @property `patternProperties` - A map of regex patterns to schemas + * @property `propertyNames` - The schema for property names + * @property `minProperties` - The minimum number of properties + * @property `maxProperties` - The maximum number of properties + * @property `dependentRequired` - A map of property names to arrays of required properties + * @property `dependentSchemas` - A map of property names to schemas + * + * **Composition Schema:** + * @property `allOf` - An array of schemas that must all be satisfied + * @property `anyOf` - An array of schemas where at least one must be satisfied + * @property `oneOf` - An array of schemas where exactly one must be satisfied + * @property `not` - A schema that must not be satisfied + * @property `if` - A schema for conditional validation + * @property `then` - A schema to apply if if condition is met + * @property `else` - A schema to apply if if condition is not met + * + * **Common Properties:** + * @property `title` - A short title for the schema + * @property `description` - A description of the schema + * @property `default` - The default value for the schema + * @property `examples` - An array of example values + * @property `enum` - An enumeration of allowed values + * @property `const` - A constant allowed value + * @property `discriminator` - A discriminator object for polymorphism + * @property `xml` - XML-specific metadata + * @property `externalDocs` - External documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The Schema Object is a discriminated union that enforces mutual-exclusion and + * co-occurrence rules. When `$ref` is present, no other properties except + * `description` and extensions are allowed. Composition keywords are mutually + * exclusive with `$ref`. + * + * ----- + * Examples + * ----- + * + * @example (reference schema): + * ```ts + * const schema: Schema = { + * $ref: "#/components/schemas/User" + * }; + * ``` + * + * @example (string schema): + * ```ts + * const schema: Schema = { + * type: "string", + * format: "email", + * maxLength: 255 + * }; + * ``` + * + * @example (object schema): + * ```ts + * const schema: Schema = { + * type: "object", + * properties: { + * name: { type: "string" }, + * age: { type: "number" } + * }, + * required: ["name"] + * }; + * ``` + * + * @example (composition schema): + * ```ts + * const schema: Schema = { + * allOf: [ + * { type: "object", properties: { name: { type: "string" } } }, + * { type: "object", properties: { age: { type: "number" } } } + * ] + * }; + * ``` + */ +export type Schema = + | ReferenceSchema + | StringSchema + | NumberSchema + | IntegerSchema + | BooleanSchema + | ArraySchema + | ObjectSchema + | CompositionSchema; diff --git a/3.2/security.ts b/3.2/security.ts new file mode 100644 index 0000000..2aca7ad --- /dev/null +++ b/3.2/security.ts @@ -0,0 +1,32 @@ +/** + * ----- + * Security Requirement Object + * ----- + * + * Lists the required security schemes to execute this operation. The name used + * for each property MUST correspond to a security scheme declared in the + * Security Schemes under the Components Object. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#security-requirement-object | OpenAPI 3.2.0 Security Requirement Object} | + * + * ----- + * Examples + * ----- + * + * @example (API key security): + * ```ts + * const security: SecurityRequirement[] = [ + * { "api_key": [] } + * ]; + * ``` + * + * @example (OAuth2 security): + * ```ts + * const security: SecurityRequirement[] = [ + * { "oauth2": ["read", "write"] } + * ]; + * ``` + */ +export type SecurityRequirement = Record; diff --git a/3.2/servers.ts b/3.2/servers.ts new file mode 100644 index 0000000..465f2ef --- /dev/null +++ b/3.2/servers.ts @@ -0,0 +1,191 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * Server Object + * ----- + * + * An object representing a Server. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-object | OpenAPI 3.2.0 Server Object} | + * + * ----- + * Fields + * ----- + * + * @property `url` - Required A URL to the target host + * @property `description` - Optional An optional string describing the host designated by the URL + * @property `variables` - Optional A map between a variable name and its value + * @property `x-${string}` - Specification Extensions + * + * @note + * The `url` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple server): + * ```ts + * const server: Server = { + * url: "https://api.example.com/v1" + * }; + * ``` + * + * @example (server with variables): + * ```ts + * const server: Server = { + * url: "https://{username}.gigantic-server.com:{port}/{basePath}", + * description: "The production API server", + * variables: { + * username: { + * default: "demo", + * description: "this value is assigned by the service provider" + * }, + * port: { + * enum: ["8443", "443"], + * default: "8443" + * }, + * basePath: { + * default: "v2" + * } + * } + * }; + * ``` + */ +export interface Server extends Extension { + /** + * A URL to the target host. + * This URL supports Server Variables and MAY be relative, to indicate that the host + * location is relative to the location where the OpenAPI document is being served. + * Variable substitutions will be made when a variable is named in {brackets}. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-object | OpenAPI 3.2.0 Server Object - url} | + * + * @property `url` - Required A URL to the target host + * + * @example "https://api.example.com/v1" + */ + url: string; + + /** + * An optional string describing the host designated by the URL. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-object | OpenAPI 3.2.0 Server Object - description} | + * + * @property `description` - Optional An optional string describing the host designated by the URL + * + * @example "The production API server" + */ + description?: string; + + /** + * A map between a variable name and its value. + * The value is used for substitution in the server's URL template. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-object | OpenAPI 3.2.0 Server Object - variables} | + * + * @property `variables` - Optional A map between a variable name and its value + * + * @example { username: { default: "demo" }, port: { default: "8443" } } + */ + variables?: Record; +} + +/** + * ----- + * Server Variable Object + * ----- + * + * An object representing a Server Variable for server URL template substitution. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-variable-object | OpenAPI 3.2.0 Server Variable Object} | + * + * ----- + * Fields + * ----- + * + * @property `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set + * @property `default` - Required The default value to use for substitution + * @property `description` - Optional An optional description for the server variable + * @property `x-${string}` - Specification Extensions + * + * @note + * The `default` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple server variable): + * ```ts + * const serverVariable: ServerVariable = { + * default: "demo" + * }; + * ``` + * + * @example (server variable with enum): + * ```ts + * const serverVariable: ServerVariable = { + * enum: ["8443", "443"], + * default: "8443", + * description: "The port number" + * }; + * ``` + */ +export interface ServerVariable extends Extension { + /** + * An enumeration of string values to be used if the substitution options + * are from a limited set. The array SHOULD NOT be empty. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-variable-object | OpenAPI 3.2.0 Server Variable Object - enum} | + * + * @property `enum` - Optional An enumeration of string values to be used if the substitution options are from a limited set + * + * @example ["8443", "443"] + */ + enum?: string[]; + + /** + * The default value to use for substitution, which SHALL be sent if an + * alternate value is not supplied. Note this behavior is different than + * the Schema Object's treatment of default values, because in those cases + * parameter values are optional. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-variable-object | OpenAPI 3.2.0 Server Variable Object - default} | + * + * @property `default` - Required The default value to use for substitution + * + * @example "demo" + */ + default: string; + + /** + * An optional description for the server variable. + * CommonMark syntax MAY be used for rich text representation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#server-variable-object | OpenAPI 3.2.0 Server Variable Object - description} | + * + * @property `description` - Optional An optional description for the server variable + * + * @example "this value is assigned by the service provider" + */ + description?: string; +} diff --git a/3.2/spec.ts b/3.2/spec.ts new file mode 100644 index 0000000..a2b4029 --- /dev/null +++ b/3.2/spec.ts @@ -0,0 +1,281 @@ +import type { Components } from "./components"; +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; +import type { Info } from "./info"; +import type { Paths } from "./paths"; +import type { SecurityRequirement } from "./security"; +import type { Server } from "./servers"; +import type { Tag } from "./tags"; +import type { Webhooks } from "./webhooks"; + +/** + * ----- + * OpenAPI Specification + * ----- + * + * This is the root object of the OpenAPI document. It contains all the information + * needed to describe an API, including metadata, servers, paths, components, and more. + * + * The OpenAPI Specification (OAS) defines a standard, language-agnostic interface + * to RESTful APIs which allows both humans and computers to discover and understand + * the capabilities of the service without access to source code, documentation, or + * through network traffic inspection. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object} | + * + * ----- + * Fields + * ----- + * + * @property `openapi` - Required The version number of the OpenAPI Specification + * @property `info` - Required Provides metadata about the API + * @property `jsonSchemaDialect` - Optional The default value for the $schema keyword within Schema Objects + * @property `servers` - Optional An array of Server Objects + * @property `paths` - Optional The available paths and operations for the API + * @property `webhooks` - Optional The incoming webhooks that MAY be received as part of this API + * @property `components` - Optional An element to hold various schemas for the document + * @property `security` - Optional A declaration of which security mechanisms can be used across the API + * @property `tags` - Optional A list of tags used by the document with additional metadata + * @property `externalDocs` - Optional Additional external documentation + * @property `x-${string}` - Specification Extensions + * + * @note + * The `openapi` and `info` fields are required. + * + * ----- + * Examples + * ----- + * + * @example (minimal specification): + * ```ts + * const spec: Specification = { + * openapi: "3.2.0", + * info: { + * title: "Pet Store API", + * version: "1.0.0" + * } + * }; + * ``` + * + * @example (complete specification): + * ```ts + * const spec: Specification = { + * openapi: "3.2.0", + * info: { + * title: "Pet Store API", + * summary: "A sample API that uses a petstore as an example", + * description: "This is a sample server Petstore server.", + * termsOfService: "http://example.com/terms/", + * contact: { + * name: "API Support", + * url: "http://www.example.com/support", + * email: "support@example.com" + * }, + * license: { + * name: "Apache 2.0", + * url: "https://www.apache.org/licenses/LICENSE-2.0.html" + * }, + * version: "1.0.0" + * }, + * servers: [ + * { + * url: "https://api.example.com/v1", + * description: "The production API server" + * } + * ], + * paths: { + * "/pets": { + * "get": { + * "summary": "List all pets", + * "responses": { + * "200": { + * "description": "A list of pets" + * } + * } + * } + * } + * }, + * webhooks: { + * "newPet": { + * "post": { + * "requestBody": { + * "description": "Information about a new pet" + * }, + * "responses": { + * "200": { + * "description": "Webhook processed successfully" + * } + * } + * } + * } + * }, + * components: { + * schemas: { + * Pet: { + * type: "object", + * properties: { + * id: { type: "integer", format: "int64" }, + * name: { type: "string" } + * } + * } + * } + * }, + * tags: [ + * { + * name: "pets", + * description: "Pet store operations" + * } + * ] + * }; + * ``` + */ +export interface Specification extends Extension { + /** + * This string MUST be the version number of the OpenAPI Specification that the + * OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret + * the OpenAPI document. This is not related to the API `info.version` string. + * This field is required. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - openapi} | + * + * @property `openapi` - Required The version number of the OpenAPI Specification + * + * @example "3.2.0" + */ + openapi: string; + + /** + * Provides metadata about the API. The metadata MAY be used by tooling as required. + * This field is required. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - info} | + * + * @property `info` - Required Provides metadata about the API + * + * @example { title: "Pet Store API", version: "1.0.0" } + */ + info: Info; + + /** + * The default value for the `$schema` keyword within Schema Objects contained + * within this OAS document. This MUST be in the form of a URI. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - jsonSchemaDialect} | + * + * @property `jsonSchemaDialect` - Optional The default value for the $schema keyword within Schema Objects + * + * @example "https://json-schema.org/draft/2020-12/schema" + */ + jsonSchemaDialect?: string; + + /** + * An array of Server Objects, which provide connectivity information to a target + * server. If the `servers` property is not provided, or is an empty array, the + * default value would be a Server Object with a `url` value of `/`. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - servers} | + * + * @property `servers` - Optional An array of Server Objects + * + * @example [{ url: "https://api.example.com/v1", description: "The production API server" }] + */ + servers?: Server[]; + + /** + * The available paths and operations for the API. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - paths} | + * + * @property `paths` - Optional The available paths and operations for the API + * + * @example { "/pets": { "get": { "summary": "List all pets", "responses": { "200": { "description": "A list of pets" } } } } } + */ + paths?: Paths; + + /** + * The incoming webhooks that MAY be received as part of this API and that the + * API consumer MAY choose to implement. Closely related to the `callbacks` feature, + * this section describes requests initiated other than by an API call, for example + * by an out of band registration. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - webhooks} | + * + * @property `webhooks` - Optional The incoming webhooks that MAY be received as part of this API + * + * @example { "newPet": { "post": { "requestBody": { "description": "Information about a new pet" } } } } + */ + webhooks?: Webhooks; + + /** + * An element to hold various schemas for the document. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - components} | + * + * @property `components` - Optional An element to hold various schemas for the document + * + * @example { schemas: { Pet: { type: "object", properties: { id: { type: "integer" } } } } } + */ + components?: Components; + + /** + * A declaration of which security mechanisms can be used across the API. The list + * of values includes alternative security requirement objects that can be used. + * Only one of the security requirement objects need to be satisfied to authorize + * a request. Individual operations can override this definition. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - security} | + * + * @property `security` - Optional A declaration of which security mechanisms can be used across the API + * + * @example [{ "api_key": [] }] + */ + security?: SecurityRequirement[]; + + /** + * A list of tags used by the document with additional metadata. The order of the + * tags can be used to reflect on their order by the parsing tools. Not all tags + * that are used by the Operation Object must be declared. The tags that are not + * declared MAY be organized randomly or based on the tools' logic. Each tag name + * in the list MUST be unique. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - tags} | + * + * @property `tags` - Optional A list of tags used by the document with additional metadata + * + * @example [{ name: "pets", description: "Pet store operations" }] + */ + tags?: Tag[]; + + /** + * Additional external documentation. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#openapi-object | OpenAPI 3.2.0 OpenAPI Object - externalDocs} | + * + * @property `externalDocs` - Optional Additional external documentation + * + * @example { description: "Find out more about our API", url: "https://example.com/docs" } + */ + externalDocs?: ExternalDocumentation; +} diff --git a/3.2/status.ts b/3.2/status.ts new file mode 100644 index 0000000..cbc0a2c --- /dev/null +++ b/3.2/status.ts @@ -0,0 +1,999 @@ +import type { Response } from "./components"; + +/** + * Swagger 2.0 Valid HTTP Status Codes + * + * Enumerates individual HTTP status codes (as keys) plus the special `"default"` key, + * per the IANA HTTP Status Code Registry. JSDoc reason phrases and references mirror + * the registry entries. See also RFC 9110 (HTTP Semantics) section mappings. + * + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA: HTTP Status Code Registry} + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html | RFC 9110: HTTP Semantics} + */ +export interface ResponsesMap { + //#region Family Codes + + /** 1xx — Informational + * + * Indicates that the request was received and the server is continuing to process it. + * + * Used for provisional responses that indicate the server has received the request and is continuing to process it. These responses are typically used for status updates during long-running operations or to indicate that the server is ready to receive additional data. + * + * The client should continue waiting for the final response. These are provisional responses and the client should not consider the request complete until receiving a final status code. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "1xx"?: Response; + + /** 2xx — Success + * + * Indicates that the request was successfully received, understood, and accepted. + * + * Used for successful operations where the request was processed successfully and the response contains the requested data or indicates successful completion of the operation. + * + * The operation completed successfully. The response body typically contains the requested data or confirmation of the successful operation. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "2xx"?: Response; + + /** 3xx — Redirection + * + * Indicates that further action needs to be taken by the client to complete the request. + * + * Used when the client needs to take additional action to complete the request, such as following a redirect, providing authentication, or accessing the resource at a different location. + * + * The client needs to take additional action to complete the request. This may involve following a redirect, providing authentication, or accessing the resource at a different location. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "3xx"?: Response; + + /** 4xx — Client Error + * + * Indicates that the request contains bad syntax or cannot be fulfilled by the server. + * + * Used when the client has sent an invalid request, such as malformed syntax, invalid parameters, authentication failures, or requests for non-existent resources. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "4xx"?: Response; + + /** 5xx — Server Error + * + * Indicates that the server failed to fulfill a valid request. + * + * Used when the server encounters an error while processing a valid request, such as internal server errors, service unavailability, or gateway timeouts. + * + * The server encountered an error while processing the request. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://spec.openapis.org/oas/v3.0.3#responses-object | OpenAPI 3.0.3 Responses Object} + */ + "5xx"?: Response; + + //#endregion + + //#region 1xx — Informational + + /** 100 Continue + * + * Indicates that the initial part of the request has been received and the client should continue with the request. + * + * The server has received the request headers and the client should proceed to send the request body. + * + * Used in scenarios where the client needs to send a large request body and wants to confirm the server is ready to receive it before sending the data. Commonly used with `Expect: 100-continue` header for file uploads, API requests with large payloads, or when implementing optimistic request patterns. + * + * The server is ready to process the request and the client can proceed with sending the request body. This prevents unnecessary data transmission if the server would reject the request based on headers alone. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-100-continue | RFC 9110 §15.2.1} + */ + "100"?: Response; + + /** 101 Switching Protocols + * + * Indicates that the server is switching protocols as requested by the client. + * + * The server agrees to change the application protocol within the current connection, typically from HTTP to WebSocket or other protocols. + * + * Primarily used for WebSocket connections where the client sends an `Upgrade: websocket` header and the server responds with 101 to establish the WebSocket connection. Also used for HTTP/2 upgrades, Server-Sent Events (SSE), or other protocol switching scenarios. + * + * The connection will continue using a different protocol. The response headers will contain the new protocol information, and subsequent communication will use the upgraded protocol. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-101-switching-protocols | RFC 9110 §15.2.2} + */ + "101"?: Response; + + /** 102 Processing + * + * Indicates that the server has received and is processing the request, but no response is available yet. + * + * The server has accepted the request and is processing it, but the processing is taking longer than normal and the client should continue waiting. + * + * Primarily used in WebDAV (Web Distributed Authoring and Versioning) environments for long-running operations like file uploads, batch operations, or complex data processing. Helps prevent client timeouts during extended processing periods. + * + * The request is being processed and the client should continue waiting. This prevents timeout issues during long-running operations and provides feedback that the server is actively working on the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2518 | RFC 2518 (WebDAV)} + */ + "102"?: Response; + + /** 103 Early Hints + * + * Provides early hints about the response that will be sent, allowing the client to start processing before the full response is ready. + * + * The server is sending preliminary information about the response headers and resources that will be needed, enabling the client to start optimization processes early. + * + * Used for performance optimization, particularly in web applications where the server can hint about resources (CSS, JavaScript, fonts) that will be needed for the final response. Allows browsers to start preloading resources before the main response is ready, significantly improving perceived performance. + * + * The client can start preparing for the response based on the hints provided. This is especially valuable for web applications where resource preloading can improve user experience. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8297 | RFC 8297} + */ + "103"?: Response; + + /** 104 Upload Resumption Supported — TEMPORARY + * + * Indicates that the server supports resumable uploads for the requested resource. + * + * The server is indicating that it can handle interrupted uploads and allows the client to resume uploading from where it left off. + * + * Used in file upload scenarios where large files might be interrupted due to network issues, browser crashes, or other problems. Enables clients to resume uploads without starting over, improving reliability for large file transfers and reducing bandwidth waste. + * + * The client can implement resumable upload logic, typically using range requests or specialized upload protocols. This is particularly valuable for mobile applications and unreliable network conditions. + * + * @note Temporary registration; see IANA entry for current status/expiry. + * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-resumable-upload-05 | draft-ietf-httpbis-resumable-upload-05} + * @see {@link https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml | IANA registry} + */ + "104"?: Response; + + //#endregion + + //#region 2xx — Success + + /** 200 OK + * + * Indicates that the request has succeeded and the response contains the requested data. + * + * The request was processed successfully and the response body contains the requested resource or data. + * + * The most common success response for GET requests, API endpoints that return data, and successful operations. Used for retrieving resources, executing queries, and any operation that completes successfully with data to return. + * + * The operation completed successfully and the response body contains the requested information. This is the standard success response for most API operations. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok | RFC 9110 §15.3.1} + */ + "200"?: Response; + + /** 201 Created + * + * Indicates that the request has succeeded and a new resource has been created as a result. + * + * The request was processed successfully and resulted in the creation of a new resource. The response typically includes the location of the newly created resource. + * + * Used for POST requests that create new resources (users, posts, files, etc.). The response should include a `Location` header pointing to the newly created resource. Common in REST APIs for resource creation operations. + * + * A new resource was successfully created and the response contains information about the created resource, typically including its ID and location. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-201-created | RFC 9110 §15.3.2} + */ + "201"?: Response; + + /** 202 Accepted + * + * Indicates that the request has been accepted for processing, but the processing has not been completed. + * + * The request was valid and accepted, but the server will process it asynchronously. The processing may or may not eventually succeed. + * + * Used for asynchronous operations like background jobs, batch processing, email sending, or any operation that takes time to complete. The client should not assume the operation succeeded based on this response alone. + * + * The request was accepted and is being processed asynchronously. The client should check the status separately or wait for a callback/webhook to know the final result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted | RFC 9110 §15.3.3} + */ + "202"?: Response; + + /** 203 Non-Authoritative Information + * + * Indicates that the request was successful, but the information returned is from a transformed or cached version of the original resource. + * + * The response is successful but the data may have been modified by a transforming proxy or cache, and may not be the authoritative version. + * + * Used when responses come from caches, proxies, or transformation services where the data might be slightly different from the original. Common in CDN scenarios or when data is processed through middleware. + * + * The request succeeded but the response data may not be the most current or authoritative version. The client should be aware that the data might be cached or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-203-non-authoritative-informat | RFC 9110 §15.3.4} + */ + "203"?: Response; + + /** 204 No Content + * + * Indicates that the request has succeeded but there is no content to return in the response body. + * + * The request was processed successfully but the response body is intentionally empty. The client should not expect any content. + * + * Used for DELETE operations, PUT requests that don't return data, or any operation where success is indicated by the absence of content. Common in REST APIs for operations that modify state without returning data. + * + * The operation completed successfully but no data is returned. The client should not attempt to parse a response body. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-204-no-content | RFC 9110 §15.3.5} + */ + "204"?: Response; + + /** 205 Reset Content + * + * Indicates that the request has succeeded and the client should reset the document view that caused the request to be sent. + * + * The request was processed successfully and the client should clear any form data or reset the user interface state. + * + * Used in web applications where form submissions should clear the form after successful processing, or when the client needs to reset its state. Common in form handling and user interface operations. + * + * The operation succeeded and the client should reset its current state, typically clearing forms or resetting the user interface. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-205-reset-content | RFC 9110 §15.3.6} + */ + "205"?: Response; + + /** 206 Partial Content + * + * Indicates that the server is delivering only part of the resource due to a range request. + * + * The request included a Range header and the server is returning only the requested portion of the resource, along with information about the range delivered. + * + * Used for resumable downloads, video streaming, large file transfers, and any scenario where the client requests a specific portion of a resource. Enables efficient handling of large files and interrupted downloads. + * + * The response contains only a portion of the requested resource. The client should expect partial content and may need to make additional requests for the complete resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-206-partial-content | RFC 9110 §15.3.7} + */ + "206"?: Response; + + /** 207 Multi-Status + * + * Indicates that multiple independent operations might have been performed, and the status of each operation is reported in the response body. + * + * The response contains multiple status codes for different operations, typically in XML format with individual operation results. + * + * Used in WebDAV environments for batch operations, bulk file operations, or any scenario where multiple independent operations are performed in a single request. Common in file management systems and collaborative editing platforms. + * + * Multiple operations were attempted and the response contains the status of each individual operation. The client should parse the response body to determine which operations succeeded or failed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "207"?: Response; + + /** 208 Already Reported + * + * Indicates that the members of a DAV binding have already been enumerated in a previous response to this request, and are not being included again. + * + * Used in WebDAV to avoid repeating the same information in a multi-status response when the same binding has already been reported. + * + * Used in WebDAV environments to optimize responses by avoiding duplicate information in multi-status responses. Helps reduce response size and improve performance in complex file system operations. + * + * The information for this binding has already been reported in a previous part of the response. The client should not expect additional information for this specific binding. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "208"?: Response; + + /** 226 IM Used + * + * Indicates that the server has fulfilled a request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance. + * + * The response represents the result of applying instance manipulations (like delta encoding) to the current resource instance. + * + * Used in scenarios involving delta encoding, instance manipulations, or when the response represents a transformed version of the resource. Common in content delivery networks and systems that optimize data transmission. + * + * The response contains a manipulated version of the resource, typically optimized for transmission. The client should be aware that the data has been processed or transformed. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc3229 | RFC 3229} + */ + "226"?: Response; + + //#endregion + + //#region 3xx — Redirection + + /** 300 Multiple Choices + * + * Indicates that the request has multiple possible responses and the client should choose one. + * + * The server has multiple representations of the requested resource and the client must choose which one to use. + * + * Used when content negotiation results in multiple valid options, such as different formats (JSON, XML, HTML) or different languages. The response typically includes a list of available options with their characteristics. + * + * The client should examine the available options and make a choice, typically by sending another request with more specific preferences or headers. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-300-multiple-choices | RFC 9110 §15.4.1} + */ + "300"?: Response; + + /** 301 Moved Permanently + * + * Indicates that the requested resource has been permanently moved to a new location. + * + * The resource has been permanently relocated and all future requests should be directed to the new URL provided in the Location header. + * + * Used when resources are permanently relocated, such as when changing domain names, restructuring URLs, or moving content to new locations. Browsers and clients should update their bookmarks and caches. + * + * The resource has moved permanently and the client should update all references to use the new URL. Search engines and caches should update their indexes. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-301-moved-permanently | RFC 9110 §15.4.2} + */ + "301"?: Response; + + /** 302 Found + * + * Indicates that the requested resource has been temporarily moved to a different location. + * + * The resource is temporarily available at a different URL, but the original URL should continue to be used for future requests. + * + * Used for temporary redirects such as maintenance pages, temporary content moves, or when the resource is temporarily unavailable at the original location. The original URL remains valid. + * + * The resource is temporarily at a different location. The client should follow the redirect but continue using the original URL for future requests. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-302-found | RFC 9110 §15.4.3} + */ + "302"?: Response; + + /** 303 See Other + * + * Indicates that the response to the request can be found at a different URL and should be retrieved using a GET request. + * + * The request was processed but the response is available at a different location, and the client should use GET to retrieve it. + * + * Used in POST-redirect-GET patterns, form submissions that redirect to a results page, or when the response to a POST request should be retrieved via GET. Common in web applications for avoiding duplicate form submissions. + * + * The client should make a GET request to the provided URL to retrieve the response. This prevents duplicate submissions and provides a clean URL for the result. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-303-see-other | RFC 9110 §15.4.4} + */ + "303"?: Response; + + /** 304 Not Modified + * + * Indicates that the resource has not been modified since the last request, so the cached version can be used. + * + * The resource has not changed since the last request, and the client can use its cached version. No response body is included. + * + * Used for caching optimization when the client sends conditional headers (If-Modified-Since, If-None-Match). Reduces bandwidth usage and improves performance by avoiding unnecessary data transfer. + * + * The resource has not changed and the client should use its cached version. This is an optimization response that saves bandwidth and improves performance. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-304-not-modified | RFC 9110 §15.4.5} + */ + "304"?: Response; + + /** 305 Use Proxy + * + * Indicates that the requested resource must be accessed through the proxy specified in the Location header. + * + * The client must use the specified proxy to access the resource. This response is rarely used in modern web applications. + * + * Used in corporate environments or specific network configurations where resources must be accessed through a particular proxy server. Mostly deprecated in modern web development. + * + * The client should use the specified proxy to access the resource. This is rarely encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy | RFC 9110 §15.4.6} + */ + "305"?: Response; + + /** 306 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code was previously used but is now reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-306-unused | RFC 9110 §15.4.7} + */ + "306"?: Response; + + /** 307 Temporary Redirect + * + * Indicates that the requested resource has been temporarily moved to a different location, and the request method should be preserved. + * + * The resource is temporarily available at a different URL, and the client should repeat the request using the same method to the new location. + * + * Used for temporary redirects where the HTTP method (POST, PUT, DELETE) should be preserved. Common in API versioning, temporary maintenance, or when resources are temporarily relocated. + * + * The resource is temporarily at a different location and the client should repeat the same request method to the new URL. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-307-temporary-redirect | RFC 9110 §15.4.8} + */ + "307"?: Response; + + /** 308 Permanent Redirect + * + * Indicates that the requested resource has been permanently moved to a different location, and the request method should be preserved. + * + * The resource has been permanently relocated and the client should use the new URL for all future requests, preserving the original HTTP method. + * + * Used for permanent redirects where the HTTP method should be preserved, such as when moving APIs to new endpoints or restructuring resource URLs. Common in API versioning and permanent relocations. + * + * The resource has moved permanently and the client should update all references to use the new URL while preserving the original HTTP method. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-308-permanent-redirect | RFC 9110 §15.4.9} + */ + "308"?: Response; + + //#endregion + + //#region 4xx — Client Error + + /** 400 Bad Request + * + * Indicates that the server cannot process the request due to a client error. + * + * The request syntax is invalid, malformed, or contains incorrect parameters that the server cannot understand or process. + * + * Used for validation errors, malformed JSON, missing required fields, invalid parameter values, or any client-side error that prevents the server from processing the request. Common in API validation scenarios. + * + * The client has sent an invalid request and should fix the request before retrying. The response body should contain details about what was wrong with the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request | RFC 9110 §15.5.1} + */ + "400"?: Response; + + /** 401 Unauthorized + * + * Indicates that the request requires authentication and the client has not provided valid credentials. + * + * The request lacks valid authentication credentials or the provided credentials are invalid, expired, or insufficient. + * + * Used when authentication is required but not provided, when login credentials are invalid, or when the authentication token has expired. Common in protected API endpoints and user authentication flows. + * + * The client needs to authenticate before accessing the resource. The response should include authentication challenge headers (WWW-Authenticate) indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized | RFC 9110 §15.5.2} + */ + "401"?: Response; + + /** 402 Payment Required + * + * Indicates that the request requires payment before it can be processed. + * + * The request cannot be fulfilled because payment is required. This status code is reserved for future use in digital payment systems. + * + * Used in payment-required scenarios, subscription services, or when access to a resource requires payment. Common in freemium models, paid API access, or premium content services. + * + * The client needs to provide payment information or complete a payment process before accessing the resource. The response should include information about how to make the payment. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required | RFC 9110 §15.5.3} + */ + "402"?: Response; + + /** 403 Forbidden + * + * Indicates that the server understood the request but refuses to authorize it. + * + * The client is authenticated but does not have permission to access the requested resource or perform the requested action. + * + * Used when the user is logged in but lacks the necessary permissions, when access is restricted based on user roles, or when the resource is not accessible to the current user. Common in authorization and access control scenarios. + * + * The client is authenticated but not authorized to access the resource. The client should not retry the request without additional permissions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden | RFC 9110 §15.5.4} + */ + "403"?: Response; + + /** 404 Not Found + * + * Indicates that the requested resource could not be found on the server. + * + * The server cannot find the requested resource at the specified URL, or the resource does not exist. + * + * Used when a resource doesn't exist, when the URL is incorrect, or when the requested item has been deleted. Common in web applications for missing pages, deleted content, or non-existent API endpoints. + * + * The requested resource does not exist. The client should verify the URL or check if the resource has been moved or deleted. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found | RFC 9110 §15.5.5} + */ + "404"?: Response; + + /** 405 Method Not Allowed + * + * Indicates that the HTTP method used in the request is not allowed for the requested resource. + * + * The resource exists but the HTTP method (GET, POST, PUT, DELETE, etc.) is not supported for this particular resource. + * + * Used when a resource only supports certain HTTP methods, such as a read-only endpoint that doesn't allow POST requests, or when the method is not implemented for the specific resource. Common in REST API design. + * + * The HTTP method is not allowed for this resource. The response should include an Allow header listing the permitted methods. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-405-method-not-allowed | RFC 9110 §15.5.6} + */ + "405"?: Response; + + /** 406 Not Acceptable + * + * Indicates that the server cannot produce a response matching the client's Accept headers. + * + * The server cannot generate a response in any of the formats requested by the client's Accept headers. + * + * Used when the client requests a specific content type (JSON, XML, HTML) that the server cannot provide, or when content negotiation fails. Common in API versioning and content type mismatches. + * + * The server cannot provide the requested content type. The client should check the Accept headers or request a different format. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable | RFC 9110 §15.5.7} + */ + "406"?: Response; + + /** 407 Proxy Authentication Required + * + * Indicates that the client must authenticate with the proxy server before the request can be processed. + * + * The proxy server requires authentication before it will forward the request to the destination server. + * + * Used in corporate environments or networks where proxy authentication is required. Common in enterprise networks, VPN connections, or when accessing resources through authenticated proxies. + * + * The client needs to authenticate with the proxy server. The response should include Proxy-Authenticate headers indicating how to authenticate. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-req | RFC 9110 §15.5.8} + */ + "407"?: Response; + + /** 408 Request Timeout + * + * Indicates that the server timed out while waiting for the request from the client. + * + * The server did not receive a complete request within the time it was prepared to wait. + * + * Used when the client takes too long to send the complete request, when network issues cause delays, or when the server has a timeout policy for request processing. Common in slow network conditions or when clients fail to send complete requests. + * + * The request timed out and the client should retry the request. The client may need to optimize the request or check network connectivity. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-408-request-timeout | RFC 9110 §15.5.9} + */ + "408"?: Response; + + /** 409 Conflict + * + * Indicates that the request conflicts with the current state of the resource. + * + * The request cannot be completed due to a conflict with the current state of the resource, such as a version mismatch or concurrent modification. + * + * Used when trying to create a resource that already exists, when there's a version conflict in concurrent editing, or when the request conflicts with business rules. Common in collaborative editing, version control, and resource creation scenarios. + * + * The request conflicts with the current state of the resource. The client should resolve the conflict before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict | RFC 9110 §15.5.10} + */ + "409"?: Response; + + /** 410 Gone + * + * Indicates that the requested resource is no longer available and will not be available again. + * + * The resource has been permanently removed and will not be restored. This is different from 404, which indicates the resource was never found. + * + * Used when content has been permanently deleted, when resources have been removed and will not be restored, or when temporary content has expired. Common in content management systems and temporary resource scenarios. + * + * The resource has been permanently removed and will not be available again. The client should not retry the request and should update any references to this resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-410-gone | RFC 9110 §15.5.11} + */ + "410"?: Response; + + /** 411 Length Required + * + * Indicates that the server requires a Content-Length header in the request. + * + * The server cannot process the request without knowing the exact length of the request body. + * + * Used when the server needs to know the exact size of the request body before processing, such as for file uploads, large data transfers, or when implementing specific security measures. Common in file upload scenarios and certain API endpoints. + * + * The client must include a Content-Length header in the request. The client should retry the request with the proper Content-Length header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-411-length-required | RFC 9110 §15.5.12} + */ + "411"?: Response; + + /** 412 Precondition Failed + * + * Indicates that one or more preconditions in the request headers were not met. + * + * The server cannot meet the conditions specified in the request headers, such as If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-Since. + * + * Used in conditional requests where the client specifies conditions that must be met, such as version checking, cache validation, or optimistic concurrency control. Common in collaborative editing and caching scenarios. + * + * The preconditions in the request were not met. The client should check the conditions and retry the request with updated preconditions. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-412-precondition-failed | RFC 9110 §15.5.13} + */ + "412"?: Response; + + /** 413 Content Too Large + * + * Indicates that the request payload is too large for the server to process. + * + * The request body exceeds the server's maximum allowed size limit. + * + * Used when file uploads exceed size limits, when request bodies are too large for processing, or when the server has configured size restrictions. Common in file upload scenarios and API rate limiting. + * + * The request payload is too large. The client should reduce the size of the request body or split it into smaller chunks. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-413-content-too-large | RFC 9110 §15.5.14} + */ + "413"?: Response; + + /** 414 URI Too Long + * + * Indicates that the URI provided in the request is too long for the server to process. + * + * The URL exceeds the server's maximum allowed length limit. + * + * Used when URLs are too long due to excessive query parameters, when GET requests contain too much data in the URL, or when the server has configured URI length restrictions. Common in search APIs and parameter-heavy requests. + * + * The URI is too long. The client should shorten the URL or use POST instead of GET for large amounts of data. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-414-uri-too-long | RFC 9110 §15.5.15} + */ + "414"?: Response; + + /** 415 Unsupported Media Type + * + * Indicates that the server cannot process the request because the media type is not supported. + * + * The server cannot process the request body because the Content-Type is not supported or recognized. + * + * Used when the client sends data in an unsupported format, when the server only accepts specific content types, or when there's a mismatch between the expected and actual content type. Common in API endpoints with strict content type requirements. + * + * The content type is not supported. The client should check the API documentation for supported content types and retry with the correct Content-Type header. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type | RFC 9110 §15.5.16} + */ + "415"?: Response; + + /** 416 Range Not Satisfiable + * + * Indicates that the server cannot satisfy the range request specified in the Range header. + * + * The requested range is not valid for the resource, either because the range is beyond the resource size or the resource doesn't support range requests. + * + * Used when range requests are invalid, when the requested range exceeds the resource size, or when the resource doesn't support partial content requests. Common in file download scenarios and media streaming. + * + * The range request is not satisfiable. The client should check the range specification or request the full resource. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-416-range-not-satisfiable | RFC 9110 §15.5.17} + */ + "416"?: Response; + + /** 417 Expectation Failed + * + * Indicates that the server cannot meet the requirements of the Expect header. + * + * The server cannot fulfill the expectations specified in the Expect header, typically when the server cannot handle the 100-continue expectation. + * + * Used when the server cannot handle the Expect: 100-continue header, when the server doesn't support the expected behavior, or when there's a mismatch between client expectations and server capabilities. Common in HTTP/1.1 implementations. + * + * The server cannot meet the expectations in the request. The client should retry without the Expect header or adjust the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-417-expectation-failed | RFC 9110 §15.5.18} + */ + "417"?: Response; + + /** 418 (Unused) + * + * This status code is reserved and not used in current HTTP specifications. + * + * This status code is reserved and should not be used in new implementations. + * + * Not used in modern web applications. This code is reserved and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-418-unused | RFC 9110 §15.5.19} + */ + "418"?: Response; + + /** 421 Misdirected Request + * + * Indicates that the request was directed to a server that is not able to produce a response. + * + * The request was sent to a server that cannot handle it, typically due to HTTP/2 connection reuse issues or server configuration problems. + * + * Used in HTTP/2 environments when a request is sent to the wrong server due to connection reuse, when there are server configuration issues, or when the request cannot be processed by the current server instance. Common in load balancing scenarios. + * + * The request was sent to the wrong server. The client should retry the request, which may be routed to a different server. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-request | RFC 9110 §15.5.20} + */ + "421"?: Response; + + /** 422 Unprocessable Content + * + * Indicates that the request is well-formed but contains semantic errors that prevent processing. + * + * The request syntax is correct but the server cannot process the request due to semantic errors, such as validation failures or business rule violations. + * + * Used for validation errors, business rule violations, or when the request is syntactically correct but logically invalid. Common in API validation scenarios where the request format is correct but the data is invalid. + * + * The request is well-formed but contains semantic errors. The client should fix the data and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content | RFC 9110 §15.5.21} + */ + "422"?: Response; + + /** 423 Locked + * + * Indicates that the requested resource is locked and cannot be modified. + * + * The resource is locked by another process or user and cannot be accessed or modified at this time. + * + * Used in WebDAV environments for file locking, collaborative editing scenarios, or when resources are temporarily locked for maintenance. Common in document management systems and collaborative editing platforms. + * + * The resource is locked and cannot be accessed. The client should wait and retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "423"?: Response; + + /** 424 Failed Dependency + * + * Indicates that the request failed because it depended on another request that also failed. + * + * The request cannot be completed because it depends on another operation that failed, typically in batch or multi-part operations. + * + * Used in WebDAV environments for batch operations where one operation depends on another, or in complex workflows where operations have dependencies. Common in file management systems and collaborative editing scenarios. + * + * The request failed due to a dependency failure. The client should check the dependencies and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "424"?: Response; + + /** 425 Too Early + * + * Indicates that the server is unwilling to process the request because it might be replayed. + * + * The server is concerned that the request might be replayed and is unwilling to process it at this time, typically due to timing or security concerns. + * + * Used in scenarios where request replay is a security concern, such as in early data scenarios or when the server needs to prevent replay attacks. Common in security-sensitive applications and protocols. + * + * The server is unwilling to process the request due to replay concerns. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc8470 | RFC 8470} + */ + "425"?: Response; + + /** 426 Upgrade Required + * + * Indicates that the server requires the client to upgrade to a different protocol. + * + * The server requires the client to use a different protocol version or upgrade to a newer version to access the resource. + * + * Used when the server requires protocol upgrades, when the client is using an outdated protocol version, or when the server only supports newer protocol versions. Common in API versioning and protocol migration scenarios. + * + * The client must upgrade to a different protocol version. The response should include upgrade information. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-426-upgrade-required | RFC 9110 §15.5.22} + */ + "426"?: Response; + + /** 428 Precondition Required + * + * Indicates that the server requires the request to include certain preconditions. + * + * The server requires the client to include specific preconditions in the request headers before it will process the request. + * + * Used when the server requires specific preconditions for security or consistency reasons, such as requiring If-Match headers for optimistic concurrency control or other conditional headers. Common in collaborative editing and version control scenarios. + * + * The server requires specific preconditions. The client should include the required preconditions and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "428"?: Response; + + /** 429 Too Many Requests + * + * Indicates that the client has sent too many requests in a given time period and should slow down. + * + * The client has exceeded the rate limit and the server is refusing to process additional requests until the rate limit resets. + * + * Used for rate limiting, API throttling, and preventing abuse. Common in API endpoints that need to control request frequency, prevent spam, or manage resource usage. Often includes retry-after headers. + * + * The client has exceeded the rate limit and should slow down. The client should wait before retrying the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "429"?: Response; + + /** 431 Request Header Fields Too Large + * + * Indicates that the server is unwilling to process the request because the header fields are too large. + * + * The request headers exceed the server's maximum allowed size limit. + * + * Used when request headers are too large, when there are too many headers, or when individual headers exceed size limits. Common in scenarios with large authentication tokens or excessive header data. + * + * The request headers are too large. The client should reduce the size of the headers and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "431"?: Response; + + /** 451 Unavailable For Legal Reasons + * + * Indicates that the requested resource is unavailable due to legal reasons. + * + * The resource is not available due to legal restrictions, such as censorship, court orders, or regulatory requirements. + * + * Used when content is blocked due to legal restrictions, when resources are unavailable in certain jurisdictions, or when there are regulatory compliance issues. Common in content delivery networks and international services. + * + * The resource is unavailable due to legal restrictions. The client should not retry the request as it will not be available. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc7725 | RFC 7725} + */ + "451"?: Response; + + //#endregion + + //#region 5xx — Server Error + + /** 500 Internal Server Error + * + * Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. + * + * The server encountered an internal error or exception that prevented it from processing the request successfully. + * + * Used for server-side errors, unhandled exceptions, database connection failures, or any unexpected server-side issue. Common in applications when there are bugs, configuration issues, or resource problems. + * + * The server encountered an internal error. The client should retry the request later, as this is typically a temporary issue. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error | RFC 9110 §15.6.1} + */ + "500"?: Response; + + /** 501 Not Implemented + * + * Indicates that the server does not support the functionality required to fulfill the request. + * + * The server does not recognize the request method or lacks the ability to fulfill the request. + * + * Used when the server doesn't support the requested HTTP method, when functionality is not implemented, or when the server cannot handle the request. Common in API development when endpoints are not yet implemented. + * + * The server does not support the requested functionality. The client should check the API documentation for supported methods and features. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-501-not-implemented | RFC 9110 §15.6.2} + */ + "501"?: Response; + + /** 502 Bad Gateway + * + * Indicates that the server, while acting as a gateway or proxy, received an invalid response from an upstream server. + * + * The server acting as a gateway or proxy received an invalid response from the upstream server it was trying to access. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server returns an invalid response or is unreachable. Common in microservices architectures and distributed systems. + * + * The gateway received an invalid response from the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway | RFC 9110 §15.6.3} + */ + "502"?: Response; + + /** 503 Service Unavailable + * + * Indicates that the server is temporarily unable to handle the request due to maintenance or overload. + * + * The server is temporarily unavailable, typically due to maintenance, overload, or temporary resource constraints. + * + * Used during server maintenance, when the server is overloaded, when there are temporary resource issues, or when the service is temporarily down. Common in high-traffic scenarios and planned maintenance windows. + * + * The server is temporarily unavailable. The client should retry the request later, often with exponential backoff. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable | RFC 9110 §15.6.4} + */ + "503"?: Response; + + /** 504 Gateway Timeout + * + * Indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server. + * + * The gateway or proxy server timed out while waiting for a response from the upstream server. + * + * Used in load balancers, reverse proxies, and API gateways when the upstream server takes too long to respond. Common in microservices architectures where services have different response times. + * + * The gateway timed out waiting for the upstream server. The client should retry the request later. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-504-gateway-timeout | RFC 9110 §15.6.5} + */ + "504"?: Response; + + /** 505 HTTP Version Not Supported + * + * Indicates that the server does not support the HTTP protocol version used in the request. + * + * The server does not support the HTTP protocol version specified in the request. + * + * Used when the client uses an unsupported HTTP version, when the server only supports specific HTTP versions, or when there are protocol version mismatches. Common in legacy systems and protocol migration scenarios. + * + * The server does not support the HTTP version used in the request. The client should use a supported HTTP version. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-supporte | RFC 9110 §15.6.6} + */ + "505"?: Response; + + /** 506 Variant Also Negotiates + * + * Indicates that the server has an internal configuration error in which the chosen variant resource is configured to engage in transparent content negotiation. + * + * The server has a configuration error where the selected variant resource is configured to engage in transparent content negotiation, creating a negotiation loop. + * + * Used in content negotiation scenarios where there's a configuration error causing negotiation loops. Common in complex content delivery systems and advanced HTTP implementations. + * + * The server has a configuration error in content negotiation. The client should contact the server administrator. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2295 | RFC 2295} + */ + "506"?: Response; + + /** 507 Insufficient Storage + * + * Indicates that the server is unable to store the representation needed to complete the request. + * + * The server cannot store the representation required to complete the request, typically due to storage space limitations. + * + * Used in WebDAV environments when there's insufficient storage space, when the server cannot allocate storage for the request, or when storage quotas are exceeded. Common in file management systems and collaborative editing platforms. + * + * The server cannot store the required representation. The client should check storage availability and retry the request. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4918 | RFC 4918 (WebDAV)} + */ + "507"?: Response; + + /** 508 Loop Detected + * + * Indicates that the server detected an infinite loop while processing the request. + * + * The server detected an infinite loop in the request processing, typically in WebDAV operations. + * + * Used in WebDAV environments when there are infinite loops in request processing, when there are circular references in operations, or when the server detects recursive operations. Common in file management systems and collaborative editing scenarios. + * + * The server detected an infinite loop. The client should check the request for circular references and retry. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc5842 | RFC 5842 (WebDAV)} + */ + "508"?: Response; + + /** 510 Not Extended — OBSOLETED + * + * This status code is obsolete and should not be used in modern implementations. + * + * This status code was used for HTTP extensions but is now obsolete and should not be used. + * + * Not used in modern web applications. This code is obsolete and should not be implemented. + * + * This status code should not be encountered in modern web applications. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc2774 | RFC 2774 (Historic)} + * @see {@link https://datatracker.ietf.org/doc/status-change-http-experiments-to-historic/ | IETF: Status change of HTTP experiments to Historic} + */ + "510"?: Response; + + /** 511 Network Authentication Required + * + * Indicates that the client needs to authenticate to gain network access. + * + * The client must authenticate with the network before it can access the requested resource. + * + * Used in captive portal scenarios, public Wi-Fi networks, or when network-level authentication is required. Common in public networks, hotels, airports, and other locations where network access requires authentication. + * + * The client needs to authenticate with the network. The client should follow the authentication process provided by the network. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc6585 | RFC 6585} + */ + "511"?: Response; + + //#endregion + + /** default — The default response for all codes not covered individually. */ + default?: Response; +} diff --git a/3.2/tags.ts b/3.2/tags.ts new file mode 100644 index 0000000..2a67cf2 --- /dev/null +++ b/3.2/tags.ts @@ -0,0 +1,80 @@ +import type { Extension } from "./extensions"; +import type { ExternalDocumentation } from "./externalDocs"; + +/** + * ----- + * Tag Object + * ----- + * + * Adds metadata to a single tag that is used by the Tag Object. + * It is not mandatory to have a Tag Object per tag used there. + * + * Tags provide a way to organize and categorize API operations, making it easier + * for developers to understand and navigate the API. They are commonly used to + * group operations by resource type, functionality, or any other logical division. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#tag-object | OpenAPI 3.2.0 Tag Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Required The name of the tag + * @property `description` - Optional A short description for the tag + * @property `externalDocs` - Optional Additional external documentation for this tag + * @property `x-${string}` - Specification Extensions + * + * @note + * The `name` field is required. + * + * ----- + * Examples + * ----- + * + * @example (simple tag): + * ```ts + * const tag: Tag = { + * name: "users", + * description: "User management operations" + * }; + * ``` + * + * @example (tag with external documentation): + * ```ts + * const tag: Tag = { + * name: "pets", + * description: "Pet store operations", + * externalDocs: { + * description: "Find out more about pet management", + * url: "https://example.com/docs/pets" + * } + * }; + * ``` + */ +export interface Tag extends Extension { + /** + * The name of the tag. This field is required. + * + * @example "users" + * @example "pets" + * @example "authentication" + */ + name: string; + + /** + * A short description for the tag. CommonMark syntax MAY be used for rich text representation. + * + * @example "User management operations" + * @example "Pet store operations" + */ + description?: string; + + /** + * Additional external documentation for this tag. + * + * @example { description: "Find out more about user management", url: "https://example.com/docs/users" } + */ + externalDocs?: ExternalDocumentation; +} diff --git a/3.2/webhooks.ts b/3.2/webhooks.ts new file mode 100644 index 0000000..ca8e641 --- /dev/null +++ b/3.2/webhooks.ts @@ -0,0 +1,130 @@ +import type { Extension } from "./extensions"; +import type { PathItemObject } from "./paths"; +import type { Reference } from "./references"; + +/** + * ----- + * Webhooks Object + * ----- + * + * The incoming webhooks that MAY be received as part of this API and that the + * API consumer MAY choose to implement. Closely related to the `callbacks` feature, + * this section describes requests initiated other than by an API call, for example + * by an out of band registration. + * + * The key name is a unique string to refer to each webhook, while the (optionally + * referenced) Path Item Object describes a request that may be initiated by the + * API provider and the expected responses. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#webhooks-object | OpenAPI 3.2.0 Webhooks Object} | + * + * ----- + * Fields + * ----- + * + * @property `{webhookName}` - A unique string to refer to each webhook + * @property `PathItemObject` - The Path Item Object describing the webhook request + * @property `Reference` - A reference to a Path Item Object + * @property `x-${string}` - Specification Extensions + * + * @note + * Each webhook key must be a unique string identifier. The value can be either + * a Path Item Object or a Reference to a Path Item Object. + * + * ----- + * Examples + * ----- + * + * @example (simple webhook): + * ```ts + * const webhooks: Webhooks = { + * "newPet": { + * "post": { + * "requestBody": { + * "description": "Information about a new pet", + * "content": { + * "application/json": { + * "schema": { + * "$ref": "#/components/schemas/Pet" + * } + * } + * } + * }, + * "responses": { + * "200": { + * "description": "Webhook processed successfully" + * } + * } + * } + * } + * }; + * ``` + * + * @example (webhook with reference): + * ```ts + * const webhooks: Webhooks = { + * "petUpdated": { + * "$ref": "#/components/pathItems/PetUpdateWebhook" + * } + * }; + * ``` + * + * @example (multiple webhooks): + * ```ts + * const webhooks: Webhooks = { + * "newPet": { + * "post": { + * "summary": "New pet created", + * "requestBody": { + * "content": { + * "application/json": { + * "schema": { "$ref": "#/components/schemas/Pet" } + * } + * } + * }, + * "responses": { + * "200": { "description": "Success" } + * } + * } + * }, + * "petDeleted": { + * "delete": { + * "summary": "Pet deleted", + * "responses": { + * "200": { "description": "Success" } + * } + * } + * } + * }; + * ``` + * + * @example (webhook with multiple operations): + * ```ts + * const webhooks: Webhooks = { + * "petLifecycle": { + * "post": { + * "summary": "Pet created or updated", + * "requestBody": { + * "content": { + * "application/json": { + * "schema": { "$ref": "#/components/schemas/Pet" } + * } + * } + * }, + * "responses": { + * "200": { "description": "Success" } + * } + * }, + * "delete": { + * "summary": "Pet deleted", + * "responses": { + * "200": { "description": "Success" } + * } + * } + * } + * }; + * ``` + */ +export type Webhooks = Record & Extension; diff --git a/3.2/xml.ts b/3.2/xml.ts new file mode 100644 index 0000000..6eb9124 --- /dev/null +++ b/3.2/xml.ts @@ -0,0 +1,116 @@ +import type { Extension } from "./extensions"; + +/** + * ----- + * XML Object + * ----- + * + * A metadata object that allows for more fine-tuned XML model definitions. + * + * When using arrays, XML element names are not inferred (for singular/plural forms) + * and the `name` property SHOULD be used to add that information. + * + * | Version | Reference | + * |---|-----| + * | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#xml-object | OpenAPI 3.2.0 XML Object} | + * + * ----- + * Fields + * ----- + * + * @property `name` - Optional Replaces the name of the element/attribute used for the described schema property + * @property `namespace` - Optional The URI of the namespace definition + * @property `prefix` - Optional The prefix to be used for the name + * @property `attribute` - Optional Declares whether the property definition translates to an attribute instead of an element + * @property `wrapped` - Optional MAY be used only for an array definition. Signifies whether the array is wrapped + * @property `x-${string}` - Specification Extensions + * + * @note + * All fields are optional. + * + * ----- + * Examples + * ----- + * + * @example (simple XML): + * ```ts + * const xml: XML = { + * name: "user" + * }; + * ``` + * + * @example (XML with namespace): + * ```ts + * const xml: XML = { + * name: "user", + * namespace: "http://example.com/schema/user", + * prefix: "user" + * }; + * ``` + * + * @example (XML attribute): + * ```ts + * const xml: XML = { + * name: "id", + * attribute: true + * }; + * ``` + * + * @example (wrapped array): + * ```ts + * const xml: XML = { + * name: "users", + * wrapped: true + * }; + * ``` + */ +export interface XML extends Extension { + /** + * Replaces the name of the element/attribute used for the described schema property. + * When defined within the Items Object (items), it will affect the name of the individual + * XML elements within the list. When defined alongside type being array (outside the items), + * it will affect the wrapping element and only if wrapped is true. If wrapped is false, + * it will be ignored. + * + * @example "user" + * @example "id" + * @example "users" + */ + name?: string; + + /** + * The URI of the namespace definition. This MUST be in the form of an absolute URI. + * + * @example "http://example.com/schema/user" + * @example "http://www.w3.org/XML/1998/namespace" + */ + namespace?: string; + + /** + * The prefix to be used for the name. + * + * @example "user" + * @example "xml" + */ + prefix?: string; + + /** + * Declares whether the property definition translates to an attribute instead of an element. + * Default value is false. + * + * @example true + * @example false + */ + attribute?: boolean; + + /** + * MAY be used only for an array definition. Signifies whether the array is wrapped + * (for example, ``) or unwrapped + * (for example, ``). Default value is false. The definition takes effect + * only when defined alongside type being array (outside the items). + * + * @example true + * @example false + */ + wrapped?: boolean; +} diff --git a/License.ts b/License.ts index c88c28d..278b563 100644 --- a/License.ts +++ b/License.ts @@ -1,82 +1,83 @@ -import { spdxLicenseList } from "./SPDXLicenseList" +import type { spdxLicenseList } from "./SPDXLicenseList"; /** * Generic helper for creating "open enums". - * + * * Provides IntelliSense suggestions for known values `T`, * but still allows arbitrary strings without collapsing to plain `string`. - * + * * @template T - The known literal values (string union) */ -type OpenEnum = T | (string & { __openEnum?: never }) +type OpenEnum = T | (string & { __openEnum?: never }); -/** - * Known license Names. - * - * SPDX License List from spdx-license-list npm package - * Imported here as const to provide richer types for the License type. - * @see {@link https://spdx.org/licenses/ | SPDX License List} - * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} - */ -export type KnownLicenseNames = - typeof spdxLicenseList[keyof typeof spdxLicenseList]["name"] - -/** - * Known license SPDX Identifiers. - * +/** + * Known license Names. + * * SPDX License List from spdx-license-list npm package * Imported here as const to provide richer types for the License type. * @see {@link https://spdx.org/licenses/ | SPDX License List} * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} */ -export type KnownLicenseIdentifiers = keyof typeof spdxLicenseList +export type KnownLicenseNames = + (typeof spdxLicenseList)[keyof typeof spdxLicenseList]["name"]; -/** - * Known license SPDX URLs. - * +/** + * Known license SPDX Identifiers. + * * SPDX License List from spdx-license-list npm package * Imported here as const to provide richer types for the License type. * @see {@link https://spdx.org/licenses/ | SPDX License List} - * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} + * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} + */ +export type KnownLicenseIdentifiers = keyof typeof spdxLicenseList; + +/** + * Known license SPDX URLs. + * + * SPDX License List from spdx-license-list npm package + * Imported here as const to provide richer types for the License type. + * @see {@link https://spdx.org/licenses/ | SPDX License List} + * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} */ export type KnownLicenseURLs = { - [K in keyof typeof spdxLicenseList]: - typeof spdxLicenseList[K] extends { url: infer U } - ? U extends string - ? U - : never - : never -}[keyof typeof spdxLicenseList] + [K in keyof typeof spdxLicenseList]: (typeof spdxLicenseList)[K] extends { + url: infer U; + } + ? U extends string + ? U + : never + : never; +}[keyof typeof spdxLicenseList]; -/** +/** * Open enum of SPDX license names. - * Suggests all known license names, but also accepts custom strings. - * + * Suggests all known license names, but also accepts custom strings. + * * The SPDX License List is sourced from the spdx-license-list npm package * Imported here as const to provide richer types for the License type. * @see {@link https://spdx.org/licenses/ | SPDX License List} - * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} + * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} */ -export type LicenseName = OpenEnum +export type LicenseName = OpenEnum; -/** +/** * Open enum of SPDX license identifiers. * Suggests all known SPDX identifiers, but also accepts custom strings. - * + * * The SPDX License List is sourced from the spdx-license-list npm package * Imported here as const to provide richer types for the License type. * @see {@link https://spdx.org/licenses/ | SPDX License List} - * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} + * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} */ -export type LicenseIdentifier = OpenEnum +export type LicenseIdentifier = OpenEnum; -/** +/** * Open enum of SPDX license URLs. * Suggests all known license URLs, but also accepts custom strings. - * + * * The SPDX License List is sourced from the spdx-license-list npm package * Imported here as const to provide richer types for the License type. * @see {@link https://spdx.org/licenses/ | SPDX License List} - * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} + * @see {@link https://www.npmjs.com/package/spdx-license-list | spdx-license-list NPM Package} */ -export type LicenseURL = OpenEnum +export type LicenseURL = OpenEnum; diff --git a/MIGRATION.md b/MIGRATION.md deleted file mode 100644 index 4df336d..0000000 --- a/MIGRATION.md +++ /dev/null @@ -1,102 +0,0 @@ -# Migration Guide - -## Breaking Changes - -This version removes backward compatibility with legacy import paths. Please update your imports to use the new clean paths. - -## Import Path Changes - -### Before (Legacy - Removed) -```typescript -// ❌ These import paths are no longer supported -import { SchemaObject } from 'oas-types/OpenAPI-3.1.0'; -import { SchemaObject30 } from 'oas-types/OpenAPI-3.0.0'; -import { SwaggerObject } from 'oas-types/Swagger-2.0'; -``` - -### After (New Clean Paths) -```typescript -// ✅ Use these clean import paths -import { SchemaObject } from 'oas-types/3.1.0'; -import { SchemaObject30 } from 'oas-types/3.0.0'; -import { SwaggerObject } from 'oas-types/2.0'; -``` - -## Complete Import Reference - -### Atomic Types -```typescript -import { - ContactObject, - LicenseObject, - InfoObject, - ExternalDocumentationObject, - TagObject, - ReferenceObject, - ServerObject, - ServerVariableObject -} from 'oas-types/atoms'; -``` - -### Utilities -```typescript -import { - DeepPartial, - DeepRequired, - Merge, - Brand, - Versioned -} from 'oas-types/utils'; -``` - -### Common Types -```typescript -import { - HttpMethod, - HttpStatusCode, - MimeType, - JsonSchemaFormat -} from 'oas-types/common'; -``` - -### Version-Specific Types -```typescript -// Swagger 2.0 -import { SwaggerObject } from 'oas-types/2.0'; - -// OpenAPI 3.0.x -import { SchemaObject30 } from 'oas-types/3.0.0'; -import { SchemaObject30 } from 'oas-types/3.0.1'; -import { SchemaObject30 } from 'oas-types/3.0.2'; -import { SchemaObject30 } from 'oas-types/3.0.3'; -import { SchemaObject30 } from 'oas-types/3.0.4'; - -// OpenAPI 3.1.x -import { SchemaObject } from 'oas-types/3.1.0'; -import { SchemaObject } from 'oas-types/3.1.1'; -``` - -## Benefits of New Import Paths - -1. **Cleaner and shorter** - `oas-types/3.1.0` vs `oas-types/OpenAPI-3.1.0` -2. **Consistent naming** - All versions follow the same pattern -3. **Better IDE support** - Easier autocomplete and suggestions -4. **Future-proof** - Easy to add new versions following the same pattern -5. **Reduced bundle size** - No legacy exports to maintain - -## Migration Steps - -1. Update all import statements to use the new paths -2. Remove any references to legacy import paths -3. Test your application to ensure everything works correctly -4. Update any documentation or examples in your codebase - -## Need Help? - -If you encounter any issues during migration, please: -1. Check this migration guide -2. Review the examples in `/examples/` directory -3. Open an issue on GitHub with your specific use case - - - diff --git a/README.md b/README.md index d3a91a7..b5a84de 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ import { Paths, Schema, Components -} from 'oas-types/3.1.x'; +} from 'oas-types/3.1'; // OpenAPI 3.0.x import { @@ -43,7 +43,7 @@ import { Paths, Schema, Components -} from 'oas-types/3.0.x'; +} from 'oas-types/3.0'; // Swagger 2.0 import { @@ -52,17 +52,17 @@ import { Paths, Schema, Definitions -} from 'oas-types/2.0.0'; +} from 'oas-types/2.0'; ``` ### Import Specific OpenAPI Objects ```typescript // Import specific objects from any version -import { Info, Contact, License } from 'oas-types/3.1.x/info'; -import { Paths, Operation, Parameter } from 'oas-types/3.1.x/paths'; -import { Schema, StringSchema, ObjectSchema } from 'oas-types/3.1.x/schema'; -import { SecurityScheme, OAuthFlows } from 'oas-types/3.1.x/security'; +import { Info, Contact, License } from 'oas-types/3.1/info'; +import { Paths, Operation, Parameter } from 'oas-types/3.1/paths'; +import { Schema, StringSchema, ObjectSchema } from 'oas-types/3.1/schema'; +import { SecurityScheme, OAuthFlows } from 'oas-types/3.1/security'; ``` ### Import Schema Data Types (OpenAPI 3.1.x) @@ -78,56 +78,97 @@ import { Object, Composition, Reference -} from 'oas-types/3.1.x/data-types'; +} from 'oas-types/3.1/data-types'; ``` ## 📁 Project Structure ``` openapi-types/ -├── versions/ -│ ├── 2.0.0/ # Swagger 2.0 types -│ │ ├── data-types/ # Schema data types -│ │ ├── info.ts # Info Object -│ │ ├── paths.ts # Paths and Operations -│ │ ├── schema.ts # Schema definitions -│ │ ├── security.ts # Security schemes -│ │ ├── spec.ts # Main Swagger object -│ │ └── index.ts # Version exports -│ │ -│ ├── 3.0.x/ # OpenAPI 3.0.x types -│ │ ├── data-types/ # Schema data types -│ │ ├── info.ts # Info Object -│ │ ├── paths.ts # Paths and Operations -│ │ ├── schema.ts # Schema definitions -│ │ ├── security.ts # Security schemes -│ │ ├── spec.ts # Main OpenAPI object -│ │ └── index.ts # Version exports -│ │ -│ ├── 3.1.x/ # OpenAPI 3.1.x types -│ │ ├── data-types/ # Individual schema types -│ │ │ ├── string.ts # String schema -│ │ │ ├── number.ts # Number schema -│ │ │ ├── integer.ts # Integer schema -│ │ │ ├── boolean.ts # Boolean schema -│ │ │ ├── array.ts # Array schema -│ │ │ ├── object.ts # Object schema -│ │ │ ├── composition.ts # Composition schemas -│ │ │ ├── reference.ts # Reference schema -│ │ │ └── index.ts # Data type exports -│ │ ├── info.ts # Info Object -│ │ ├── paths.ts # Paths and Operations -│ │ ├── schema.ts # Main Schema union type -│ │ ├── security.ts # Security schemes -│ │ ├── spec.ts # Main OpenAPI object -│ │ └── index.ts # Version exports -│ │ -│ ├── License.ts # SPDX license definitions -│ └── SPDXLicenseList.ts # Complete SPDX license list +├── 2.0.0/ # Swagger 2.0 types +│ ├── data-types/ # Schema data types +│ │ ├── string.ts # String schema +│ │ ├── number.ts # Number schema +│ │ ├── integer.ts # Integer schema +│ │ ├── boolean.ts # Boolean schema +│ │ ├── array.ts # Array schema +│ │ ├── object.ts # Object schema +│ │ ├── composition.ts # Composition schemas +│ │ ├── reference.ts # Reference schema +│ │ └── index.ts # Data type exports +│ ├── info.ts # Info Object +│ ├── paths.ts # Paths and Operations +│ ├── schema.ts # Schema definitions +│ ├── security.ts # Security schemes +│ ├── spec.ts # Main Swagger object +│ ├── extensions.ts # Specification extensions +│ ├── externalDocs.ts # External documentation +│ ├── references.ts # Reference objects +│ ├── tags.ts # Tag objects +│ ├── xml.ts # XML objects +│ ├── example.ts # Example objects +│ ├── 2.0.md # Version documentation +│ └── index.ts # Version exports │ -├── index.ts # Main entry point -├── package.json -└── README.md +├── 3.0.x/ # OpenAPI 3.0.x types +│ ├── data-types/ # Schema data types +│ │ ├── string.ts # String schema +│ │ ├── number.ts # Number schema +│ │ ├── integer.ts # Integer schema +│ │ ├── boolean.ts # Boolean schema +│ │ ├── array.ts # Array schema +│ │ ├── object.ts # Object schema +│ │ ├── composition.ts # Composition schemas +│ │ ├── reference.ts # Reference schema +│ │ └── index.ts # Data type exports +│ ├── info.ts # Info Object +│ ├── paths.ts # Paths and Operations +│ ├── schema.ts # Schema definitions +│ ├── security.ts # Security schemes +│ ├── spec.ts # Main OpenAPI object +│ ├── components.ts # Components object +│ ├── extensions.ts # Specification extensions +│ ├── externalDocs.ts # External documentation +│ ├── references.ts # Reference objects +│ ├── servers.ts # Server objects +│ ├── tags.ts # Tag objects +│ ├── xml.ts # XML objects +│ └── index.ts # Version exports +│ +├── 3.1.x/ # OpenAPI 3.1.x types +│ ├── data-types/ # Individual schema types +│ │ ├── string.ts # String schema +│ │ ├── number.ts # Number schema +│ │ ├── integer.ts # Integer schema +│ │ ├── boolean.ts # Boolean schema +│ │ ├── array.ts # Array schema +│ │ ├── object.ts # Object schema +│ │ ├── composition.ts # Composition schemas +│ │ ├── reference.ts # Reference schema +│ │ └── index.ts # Data type exports +│ ├── info.ts # Info Object +│ ├── paths.ts # Paths and Operations +│ ├── schema.ts # Main Schema union type +│ ├── security.ts # Security schemes +│ ├── spec.ts # Main OpenAPI object +│ ├── components.ts # Components object +│ ├── extensions.ts # Specification extensions +│ ├── externalDocs.ts # External documentation +│ ├── references.ts # Reference objects +│ ├── servers.ts # Server objects +│ ├── tags.ts # Tag objects +│ ├── xml.ts # XML objects +│ ├── 3.1.0.md # OpenAPI 3.1.0 documentation +│ ├── 3.1.1.md # OpenAPI 3.1.1 documentation +│ └── index.ts # Version exports +│ +├── 3.2.0/ # OpenAPI 3.2.0 types (in development) +│ ├── 3.2.0.md # Version documentation +│ └── index.ts # Placeholder exports (not yet implemented) +│ +├── License.ts # SPDX license definitions +├── SPDXLicenseList.ts # Complete SPDX license list +└── index.ts # Main entry point ``` ## 🎯 Philosophy @@ -156,13 +197,14 @@ Every type includes: - **Swagger 2.0** (OpenAPI Specification v2.0) - Complete implementation - **OpenAPI 3.0.x** - Complete implementation with all 3.0.x variants - **OpenAPI 3.1.x** - Complete implementation with JSON Schema 2020-12 alignment +- **OpenAPI 3.2.0** - In development (not yet available for import) ## 🔧 Examples ### Basic OpenAPI 3.1.x Usage ```typescript -import { Specification, Info, Paths, Schema } from 'oas-types/3.1.x'; +import { Specification, Info, Paths, Schema } from 'oas-types/3.1'; const openApiSpec: Specification = { openapi: "3.1.0", @@ -210,7 +252,7 @@ import { ObjectSchema, ArraySchema, Schema -} from 'oas-types/3.1.x'; +} from 'oas-types/3.1'; // String schema with validation const nameSchema: StringSchema = { @@ -248,7 +290,7 @@ const usersSchema: ArraySchema = { ### Swagger 2.0 Usage ```typescript -import { Swagger, Info, Paths } from 'oas-types/2.0.0'; +import { Swagger, Info, Paths } from 'oas-types/2.0'; const swaggerSpec: Swagger = { swagger: "2.0", @@ -289,7 +331,7 @@ const swaggerSpec: Swagger = { ### Security Schemes ```typescript -import { SecurityScheme, OAuthFlows } from 'oas-types/3.1.x/security'; +import { SecurityScheme, OAuthFlows } from 'oas-types/3.1/security'; const apiKeyAuth: SecurityScheme = { type: "apiKey", diff --git a/SPDXLicenseList.ts b/SPDXLicenseList.ts index 7c3d160..70eb4c2 100644 --- a/SPDXLicenseList.ts +++ b/SPDXLicenseList.ts @@ -5,3402 +5,3402 @@ * @see https://spdx.org/licenses/ */ export const spdxLicenseList = { - "DSDP": { - "name": "DSDP License", - "url": "https://fedoraproject.org/wiki/Licensing/DSDP", - "osiApproved": false + DSDP: { + name: "DSDP License", + url: "https://fedoraproject.org/wiki/Licensing/DSDP", + osiApproved: false, }, "NIST-PD": { - "name": "NIST Public Domain Notice", - "url": "https://github.com/tcheneau/simpleRPL/blob/e645e69e38dd4e3ccfeceb2db8cba05b7c2e0cd3/LICENSE.txt", - "osiApproved": false + name: "NIST Public Domain Notice", + url: "https://github.com/tcheneau/simpleRPL/blob/e645e69e38dd4e3ccfeceb2db8cba05b7c2e0cd3/LICENSE.txt", + osiApproved: false, }, "CC-BY-NC-SA-2.0": { - "name": "Creative Commons Attribution Non Commercial Share Alike 2.0 Generic", - "url": "https://creativecommons.org/licenses/by-nc-sa/2.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 2.0 Generic", + url: "https://creativecommons.org/licenses/by-nc-sa/2.0/legalcode", + osiApproved: false, }, "NLOD-1.0": { - "name": "Norwegian Licence for Open Government Data (NLOD) 1.0", - "url": "http://data.norge.no/nlod/en/1.0", - "osiApproved": false + name: "Norwegian Licence for Open Government Data (NLOD) 1.0", + url: "http://data.norge.no/nlod/en/1.0", + osiApproved: false, }, "RHeCos-1.1": { - "name": "Red Hat eCos Public License v1.1", - "url": "http://ecos.sourceware.org/old-license.html", - "osiApproved": false + name: "Red Hat eCos Public License v1.1", + url: "http://ecos.sourceware.org/old-license.html", + osiApproved: false, }, "GFDL-1.3-no-invariants-only": { - "name": "GNU Free Documentation License v1.3 only - no invariants", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3 only - no invariants", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, - "RSCPL": { - "name": "Ricoh Source Code Public License", - "url": "http://wayback.archive.org/web/20060715140826/http://www.risource.org/RPL/RPL-1.0A.shtml", - "osiApproved": true + RSCPL: { + name: "Ricoh Source Code Public License", + url: "http://wayback.archive.org/web/20060715140826/http://www.risource.org/RPL/RPL-1.0A.shtml", + osiApproved: true, }, "ASWF-Digital-Assets-1.1": { - "name": "ASWF Digital Assets License 1.1", - "url": "https://github.com/AcademySoftwareFoundation/foundation/blob/main/digital_assets/aswf_digital_assets_license_v1.1.txt", - "osiApproved": false + name: "ASWF Digital Assets License 1.1", + url: "https://github.com/AcademySoftwareFoundation/foundation/blob/main/digital_assets/aswf_digital_assets_license_v1.1.txt", + osiApproved: false, }, "eCos-2.0": { - "name": "eCos license version 2.0", - "url": "https://www.gnu.org/licenses/ecos-license.html", - "osiApproved": false + name: "eCos license version 2.0", + url: "https://www.gnu.org/licenses/ecos-license.html", + osiApproved: false, }, - "GLWTPL": { - "name": "Good Luck With That Public License", - "url": "https://github.com/me-shaon/GLWTPL/commit/da5f6bc734095efbacb442c0b31e33a65b9d6e85", - "osiApproved": false + GLWTPL: { + name: "Good Luck With That Public License", + url: "https://github.com/me-shaon/GLWTPL/commit/da5f6bc734095efbacb442c0b31e33a65b9d6e85", + osiApproved: false, }, "Info-ZIP": { - "name": "Info-ZIP License", - "url": "http://www.info-zip.org/license.html", - "osiApproved": false + name: "Info-ZIP License", + url: "http://www.info-zip.org/license.html", + osiApproved: false, }, "LPPL-1.3c": { - "name": "LaTeX Project Public License v1.3c", - "url": "http://www.latex-project.org/lppl/lppl-1-3c.txt", - "osiApproved": true + name: "LaTeX Project Public License v1.3c", + url: "http://www.latex-project.org/lppl/lppl-1-3c.txt", + osiApproved: true, }, "zlib-acknowledgement": { - "name": "zlib/libpng License with Acknowledgement", - "url": "https://fedoraproject.org/wiki/Licensing/ZlibWithAcknowledgement", - "osiApproved": false + name: "zlib/libpng License with Acknowledgement", + url: "https://fedoraproject.org/wiki/Licensing/ZlibWithAcknowledgement", + osiApproved: false, }, - "checkmk": { - "name": "Checkmk License", - "url": "https://github.com/libcheck/check/blob/master/checkmk/checkmk.in", - "osiApproved": false + checkmk: { + name: "Checkmk License", + url: "https://github.com/libcheck/check/blob/master/checkmk/checkmk.in", + osiApproved: false, }, "OLDAP-2.8": { - "name": "Open LDAP Public License v2.8", - "url": "http://www.openldap.org/software/release/license.html", - "osiApproved": true + name: "Open LDAP Public License v2.8", + url: "http://www.openldap.org/software/release/license.html", + osiApproved: true, }, "cve-tou": { - "name": "Common Vulnerability Enumeration ToU License", - "url": "https://www.cve.org/Legal/TermsOfUse", - "osiApproved": false + name: "Common Vulnerability Enumeration ToU License", + url: "https://www.cve.org/Legal/TermsOfUse", + osiApproved: false, }, - "MirOS": { - "name": "The MirOS Licence", - "url": "https://opensource.org/licenses/MirOS", - "osiApproved": true + MirOS: { + name: "The MirOS Licence", + url: "https://opensource.org/licenses/MirOS", + osiApproved: true, }, "Parity-6.0.0": { - "name": "The Parity Public License 6.0.0", - "url": "https://paritylicense.com/versions/6.0.0.html", - "osiApproved": false + name: "The Parity Public License 6.0.0", + url: "https://paritylicense.com/versions/6.0.0.html", + osiApproved: false, }, "CC-BY-SA-2.1-JP": { - "name": "Creative Commons Attribution Share Alike 2.1 Japan", - "url": "https://creativecommons.org/licenses/by-sa/2.1/jp/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 2.1 Japan", + url: "https://creativecommons.org/licenses/by-sa/2.1/jp/legalcode", + osiApproved: false, }, - "InnoSetup": { - "name": "Inno Setup License", - "url": "https://github.com/jrsoftware/issrc/blob/HEAD/license.txt", - "osiApproved": false + InnoSetup: { + name: "Inno Setup License", + url: "https://github.com/jrsoftware/issrc/blob/HEAD/license.txt", + osiApproved: false, }, "IPL-1.0": { - "name": "IBM Public License v1.0", - "url": "https://opensource.org/licenses/IPL-1.0", - "osiApproved": true + name: "IBM Public License v1.0", + url: "https://opensource.org/licenses/IPL-1.0", + osiApproved: true, }, "Spencer-86": { - "name": "Spencer License 86", - "url": "https://fedoraproject.org/wiki/Licensing/Henry_Spencer_Reg-Ex_Library_License", - "osiApproved": false + name: "Spencer License 86", + url: "https://fedoraproject.org/wiki/Licensing/Henry_Spencer_Reg-Ex_Library_License", + osiApproved: false, }, - "JPNIC": { - "name": "Japan Network Information Center License", - "url": "https://gitlab.isc.org/isc-projects/bind9/blob/master/COPYRIGHT#L366", - "osiApproved": false + JPNIC: { + name: "Japan Network Information Center License", + url: "https://gitlab.isc.org/isc-projects/bind9/blob/master/COPYRIGHT#L366", + osiApproved: false, }, - "OpenVision": { - "name": "OpenVision License", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L66-L98", - "osiApproved": false + OpenVision: { + name: "OpenVision License", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L66-L98", + osiApproved: false, }, - "SGP4": { - "name": "SGP4 Permission Notice", - "url": "https://celestrak.org/publications/AIAA/2006-6753/faq.php", - "osiApproved": false + SGP4: { + name: "SGP4 Permission Notice", + url: "https://celestrak.org/publications/AIAA/2006-6753/faq.php", + osiApproved: false, }, "MPL-1.1": { - "name": "Mozilla Public License 1.1", - "url": "http://www.mozilla.org/MPL/MPL-1.1.html", - "osiApproved": true + name: "Mozilla Public License 1.1", + url: "http://www.mozilla.org/MPL/MPL-1.1.html", + osiApproved: true, }, "BSD-3-Clause-Clear": { - "name": "BSD 3-Clause Clear License", - "url": "http://labs.metacarta.com/license-explanation.html#license", - "osiApproved": false + name: "BSD 3-Clause Clear License", + url: "http://labs.metacarta.com/license-explanation.html#license", + osiApproved: false, }, "AML-glslang": { - "name": "AML glslang variant License", - "url": "https://github.com/KhronosGroup/glslang/blob/main/LICENSE.txt#L949", - "osiApproved": false + name: "AML glslang variant License", + url: "https://github.com/KhronosGroup/glslang/blob/main/LICENSE.txt#L949", + osiApproved: false, }, - "Vim": { - "name": "Vim License", - "url": "http://vimdoc.sourceforge.net/htmldoc/uganda.html", - "osiApproved": false + Vim: { + name: "Vim License", + url: "http://vimdoc.sourceforge.net/htmldoc/uganda.html", + osiApproved: false, }, "Community-Spec-1.0": { - "name": "Community Specification License 1.0", - "url": "https://github.com/CommunitySpecification/1.0/blob/master/1._Community_Specification_License-v1.md", - "osiApproved": false + name: "Community Specification License 1.0", + url: "https://github.com/CommunitySpecification/1.0/blob/master/1._Community_Specification_License-v1.md", + osiApproved: false, }, "OSL-3.0": { - "name": "Open Software License 3.0", - "url": "https://web.archive.org/web/20120101081418/http://rosenlaw.com:80/OSL3.0.htm", - "osiApproved": true + name: "Open Software License 3.0", + url: "https://web.archive.org/web/20120101081418/http://rosenlaw.com:80/OSL3.0.htm", + osiApproved: true, }, - "CrystalStacker": { - "name": "CrystalStacker License", - "url": "https://fedoraproject.org/wiki/Licensing:CrystalStacker?rd=Licensing/CrystalStacker", - "osiApproved": false + CrystalStacker: { + name: "CrystalStacker License", + url: "https://fedoraproject.org/wiki/Licensing:CrystalStacker?rd=Licensing/CrystalStacker", + osiApproved: false, }, "MPL-1.0": { - "name": "Mozilla Public License 1.0", - "url": "http://www.mozilla.org/MPL/MPL-1.0.html", - "osiApproved": true + name: "Mozilla Public License 1.0", + url: "http://www.mozilla.org/MPL/MPL-1.0.html", + osiApproved: true, }, "OLDAP-1.2": { - "name": "Open LDAP Public License v1.2", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=42b0383c50c299977b5893ee695cf4e486fb0dc7", - "osiApproved": false + name: "Open LDAP Public License v1.2", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=42b0383c50c299977b5893ee695cf4e486fb0dc7", + osiApproved: false, }, "Sendmail-8.23": { - "name": "Sendmail License 8.23", - "url": "https://www.proofpoint.com/sites/default/files/sendmail-license.pdf", - "osiApproved": false + name: "Sendmail License 8.23", + url: "https://www.proofpoint.com/sites/default/files/sendmail-license.pdf", + osiApproved: false, }, "CMU-Mach": { - "name": "CMU Mach License", - "url": "https://www.cs.cmu.edu/~410/licenses.html", - "osiApproved": false + name: "CMU Mach License", + url: "https://www.cs.cmu.edu/~410/licenses.html", + osiApproved: false, }, - "xpp": { - "name": "XPP License", - "url": "https://fedoraproject.org/wiki/Licensing/xpp", - "osiApproved": false + xpp: { + name: "XPP License", + url: "https://fedoraproject.org/wiki/Licensing/xpp", + osiApproved: false, }, "GPL-2.0-with-bison-exception": { - "name": "GNU General Public License v2.0 w/Bison exception", - "url": "http://git.savannah.gnu.org/cgit/bison.git/tree/data/yacc.c?id=193d7c7054ba7197b0789e14965b739162319b5e#n141", - "osiApproved": false + name: "GNU General Public License v2.0 w/Bison exception", + url: "http://git.savannah.gnu.org/cgit/bison.git/tree/data/yacc.c?id=193d7c7054ba7197b0789e14965b739162319b5e#n141", + osiApproved: false, }, "ECL-1.0": { - "name": "Educational Community License v1.0", - "url": "https://opensource.org/licenses/ECL-1.0", - "osiApproved": true + name: "Educational Community License v1.0", + url: "https://opensource.org/licenses/ECL-1.0", + osiApproved: true, }, - "Plexus": { - "name": "Plexus Classworlds License", - "url": "https://fedoraproject.org/wiki/Licensing/Plexus_Classworlds_License", - "osiApproved": false + Plexus: { + name: "Plexus Classworlds License", + url: "https://fedoraproject.org/wiki/Licensing/Plexus_Classworlds_License", + osiApproved: false, }, "Elastic-2.0": { - "name": "Elastic License 2.0", - "url": "https://www.elastic.co/licensing/elastic-license", - "osiApproved": false + name: "Elastic License 2.0", + url: "https://www.elastic.co/licensing/elastic-license", + osiApproved: false, }, "CPL-1.0": { - "name": "Common Public License 1.0", - "url": "https://opensource.org/licenses/CPL-1.0", - "osiApproved": true + name: "Common Public License 1.0", + url: "https://opensource.org/licenses/CPL-1.0", + osiApproved: true, }, "GFDL-1.2-no-invariants-only": { - "name": "GNU Free Documentation License v1.2 only - no invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2 only - no invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, "OPL-1.0": { - "name": "Open Public License v1.0", - "url": "http://old.koalateam.com/jackaroo/OPL_1_0.TXT", - "osiApproved": false + name: "Open Public License v1.0", + url: "http://old.koalateam.com/jackaroo/OPL_1_0.TXT", + osiApproved: false, }, "CC-BY-SA-4.0": { - "name": "Creative Commons Attribution Share Alike 4.0 International", - "url": "https://creativecommons.org/licenses/by-sa/4.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 4.0 International", + url: "https://creativecommons.org/licenses/by-sa/4.0/legalcode", + osiApproved: false, }, - "ADSL": { - "name": "Amazon Digital Services License", - "url": "https://fedoraproject.org/wiki/Licensing/AmazonDigitalServicesLicense", - "osiApproved": false + ADSL: { + name: "Amazon Digital Services License", + url: "https://fedoraproject.org/wiki/Licensing/AmazonDigitalServicesLicense", + osiApproved: false, }, "SGI-B-1.1": { - "name": "SGI Free Software License B v1.1", - "url": "http://oss.sgi.com/projects/FreeB/", - "osiApproved": false + name: "SGI Free Software License B v1.1", + url: "http://oss.sgi.com/projects/FreeB/", + osiApproved: false, }, "XFree86-1.1": { - "name": "XFree86 License 1.1", - "url": "http://www.xfree86.org/current/LICENSE4.html", - "osiApproved": false + name: "XFree86 License 1.1", + url: "http://www.xfree86.org/current/LICENSE4.html", + osiApproved: false, }, "Latex2e-translated-notice": { - "name": "Latex2e with translated notice permission", - "url": "https://git.savannah.gnu.org/cgit/indent.git/tree/doc/indent.texi?id=a74c6b4ee49397cf330b333da1042bffa60ed14f#n74", - "osiApproved": false + name: "Latex2e with translated notice permission", + url: "https://git.savannah.gnu.org/cgit/indent.git/tree/doc/indent.texi?id=a74c6b4ee49397cf330b333da1042bffa60ed14f#n74", + osiApproved: false, }, - "IPA": { - "name": "IPA Font License", - "url": "https://opensource.org/licenses/IPA", - "osiApproved": true + IPA: { + name: "IPA Font License", + url: "https://opensource.org/licenses/IPA", + osiApproved: true, }, - "psutils": { - "name": "psutils License", - "url": "https://fedoraproject.org/wiki/Licensing/psutils", - "osiApproved": false + psutils: { + name: "psutils License", + url: "https://fedoraproject.org/wiki/Licensing/psutils", + osiApproved: false, }, "CC-BY-NC-ND-3.0": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 3.0 Unported", - "url": "https://creativecommons.org/licenses/by-nc-nd/3.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 3.0 Unported", + url: "https://creativecommons.org/licenses/by-nc-nd/3.0/legalcode", + osiApproved: false, }, - "FSFULLR": { - "name": "FSF Unlimited License (with License Retention)", - "url": "https://fedoraproject.org/wiki/Licensing/FSF_Unlimited_License#License_Retention_Variant", - "osiApproved": false + FSFULLR: { + name: "FSF Unlimited License (with License Retention)", + url: "https://fedoraproject.org/wiki/Licensing/FSF_Unlimited_License#License_Retention_Variant", + osiApproved: false, }, "SSLeay-standalone": { - "name": "SSLeay License - standalone", - "url": "https://www.tq-group.com/filedownloads/files/software-license-conditions/OriginalSSLeay/OriginalSSLeay.pdf", - "osiApproved": false + name: "SSLeay License - standalone", + url: "https://www.tq-group.com/filedownloads/files/software-license-conditions/OriginalSSLeay/OriginalSSLeay.pdf", + osiApproved: false, }, - "MMIXware": { - "name": "MMIXware License", - "url": "https://gitlab.lrz.de/mmix/mmixware/-/blob/master/boilerplate.w", - "osiApproved": false + MMIXware: { + name: "MMIXware License", + url: "https://gitlab.lrz.de/mmix/mmixware/-/blob/master/boilerplate.w", + osiApproved: false, }, "Graphics-Gems": { - "name": "Graphics Gems License", - "url": "https://github.com/erich666/GraphicsGems/blob/master/LICENSE.md", - "osiApproved": false + name: "Graphics Gems License", + url: "https://github.com/erich666/GraphicsGems/blob/master/LICENSE.md", + osiApproved: false, }, "HPND-export-US-acknowledgement": { - "name": "HPND with US Government export control warning and acknowledgment", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L831-L852", - "osiApproved": false + name: "HPND with US Government export control warning and acknowledgment", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L831-L852", + osiApproved: false, }, "CC-BY-NC-2.0": { - "name": "Creative Commons Attribution Non Commercial 2.0 Generic", - "url": "https://creativecommons.org/licenses/by-nc/2.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial 2.0 Generic", + url: "https://creativecommons.org/licenses/by-nc/2.0/legalcode", + osiApproved: false, }, "OLDAP-1.3": { - "name": "Open LDAP Public License v1.3", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=e5f8117f0ce088d0bd7a8e18ddf37eaa40eb09b1", - "osiApproved": false + name: "Open LDAP Public License v1.3", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=e5f8117f0ce088d0bd7a8e18ddf37eaa40eb09b1", + osiApproved: false, }, "LGPL-2.1-only": { - "name": "GNU Lesser General Public License v2.1 only", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v2.1 only", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", + osiApproved: true, }, "NLOD-2.0": { - "name": "Norwegian Licence for Open Government Data (NLOD) 2.0", - "url": "http://data.norge.no/nlod/en/2.0", - "osiApproved": false + name: "Norwegian Licence for Open Government Data (NLOD) 2.0", + url: "http://data.norge.no/nlod/en/2.0", + osiApproved: false, }, "BSD-2-Clause": { - "name": "BSD 2-Clause \"Simplified\" License", - "url": "https://opensource.org/licenses/BSD-2-Clause", - "osiApproved": true + name: 'BSD 2-Clause "Simplified" License', + url: "https://opensource.org/licenses/BSD-2-Clause", + osiApproved: true, }, - "mailprio": { - "name": "mailprio License", - "url": "https://fossies.org/linux/sendmail/contrib/mailprio", - "osiApproved": false + mailprio: { + name: "mailprio License", + url: "https://fossies.org/linux/sendmail/contrib/mailprio", + osiApproved: false, }, "CC-BY-SA-3.0": { - "name": "Creative Commons Attribution Share Alike 3.0 Unported", - "url": "https://creativecommons.org/licenses/by-sa/3.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 3.0 Unported", + url: "https://creativecommons.org/licenses/by-sa/3.0/legalcode", + osiApproved: false, }, - "Noweb": { - "name": "Noweb License", - "url": "https://fedoraproject.org/wiki/Licensing/Noweb", - "osiApproved": false + Noweb: { + name: "Noweb License", + url: "https://fedoraproject.org/wiki/Licensing/Noweb", + osiApproved: false, }, - "Soundex": { - "name": "Soundex License", - "url": "https://metacpan.org/release/RJBS/Text-Soundex-3.05/source/Soundex.pm#L3-11", - "osiApproved": false + Soundex: { + name: "Soundex License", + url: "https://metacpan.org/release/RJBS/Text-Soundex-3.05/source/Soundex.pm#L3-11", + osiApproved: false, }, "CECILL-1.0": { - "name": "CeCILL Free Software License Agreement v1.0", - "url": "http://www.cecill.info/licences/Licence_CeCILL_V1-fr.html", - "osiApproved": false + name: "CeCILL Free Software License Agreement v1.0", + url: "http://www.cecill.info/licences/Licence_CeCILL_V1-fr.html", + osiApproved: false, }, - "Aladdin": { - "name": "Aladdin Free Public License", - "url": "http://pages.cs.wisc.edu/~ghost/doc/AFPL/6.01/Public.htm", - "osiApproved": false + Aladdin: { + name: "Aladdin Free Public License", + url: "http://pages.cs.wisc.edu/~ghost/doc/AFPL/6.01/Public.htm", + osiApproved: false, }, "SSH-OpenSSH": { - "name": "SSH OpenSSH license", - "url": "https://github.com/openssh/openssh-portable/blob/1b11ea7c58cd5c59838b5fa574cd456d6047b2d4/LICENCE#L10", - "osiApproved": false + name: "SSH OpenSSH license", + url: "https://github.com/openssh/openssh-portable/blob/1b11ea7c58cd5c59838b5fa574cd456d6047b2d4/LICENCE#L10", + osiApproved: false, }, "BSD-Attribution-HPND-disclaimer": { - "name": "BSD with Attribution and HPND disclaimer", - "url": "https://github.com/cyrusimap/cyrus-sasl/blob/master/COPYING", - "osiApproved": false + name: "BSD with Attribution and HPND disclaimer", + url: "https://github.com/cyrusimap/cyrus-sasl/blob/master/COPYING", + osiApproved: false, }, "CC-BY-NC-SA-2.0-UK": { - "name": "Creative Commons Attribution Non Commercial Share Alike 2.0 England and Wales", - "url": "https://creativecommons.org/licenses/by-nc-sa/2.0/uk/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 2.0 England and Wales", + url: "https://creativecommons.org/licenses/by-nc-sa/2.0/uk/legalcode", + osiApproved: false, }, - "Kazlib": { - "name": "Kazlib License", - "url": "http://git.savannah.gnu.org/cgit/kazlib.git/tree/except.c?id=0062df360c2d17d57f6af19b0e444c51feb99036", - "osiApproved": false + Kazlib: { + name: "Kazlib License", + url: "http://git.savannah.gnu.org/cgit/kazlib.git/tree/except.c?id=0062df360c2d17d57f6af19b0e444c51feb99036", + osiApproved: false, }, "Ubuntu-font-1.0": { - "name": "Ubuntu Font Licence v1.0", - "url": "https://ubuntu.com/legal/font-licence", - "osiApproved": false + name: "Ubuntu Font Licence v1.0", + url: "https://ubuntu.com/legal/font-licence", + osiApproved: false, }, "SGI-OpenGL": { - "name": "SGI OpenGL License", - "url": "https://gitlab.freedesktop.org/mesa/glw/-/blob/master/README?ref_type=heads", - "osiApproved": false + name: "SGI OpenGL License", + url: "https://gitlab.freedesktop.org/mesa/glw/-/blob/master/README?ref_type=heads", + osiApproved: false, }, - "Rdisc": { - "name": "Rdisc License", - "url": "https://fedoraproject.org/wiki/Licensing/Rdisc_License", - "osiApproved": false + Rdisc: { + name: "Rdisc License", + url: "https://fedoraproject.org/wiki/Licensing/Rdisc_License", + osiApproved: false, }, "HPND-sell-variant-MIT-disclaimer": { - "name": "HPND sell variant with MIT disclaimer", - "url": "https://github.com/sigmavirus24/x11-ssh-askpass/blob/master/README", - "osiApproved": false + name: "HPND sell variant with MIT disclaimer", + url: "https://github.com/sigmavirus24/x11-ssh-askpass/blob/master/README", + osiApproved: false, }, - "LGPLLR": { - "name": "Lesser General Public License For Linguistic Resources", - "url": "http://www-igm.univ-mlv.fr/~unitex/lgpllr.html", - "osiApproved": false + LGPLLR: { + name: "Lesser General Public License For Linguistic Resources", + url: "http://www-igm.univ-mlv.fr/~unitex/lgpllr.html", + osiApproved: false, }, - "OAR": { - "name": "OAR License", - "url": "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/string/strsignal.c;hb=HEAD#l35", - "osiApproved": false + OAR: { + name: "OAR License", + url: "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/string/strsignal.c;hb=HEAD#l35", + osiApproved: false, }, - "HTMLTIDY": { - "name": "HTML Tidy License", - "url": "https://github.com/htacg/tidy-html5/blob/next/README/LICENSE.md", - "osiApproved": false + HTMLTIDY: { + name: "HTML Tidy License", + url: "https://github.com/htacg/tidy-html5/blob/next/README/LICENSE.md", + osiApproved: false, }, - "AMPAS": { - "name": "Academy of Motion Picture Arts and Sciences BSD", - "url": "https://fedoraproject.org/wiki/Licensing/BSD#AMPASBSD", - "osiApproved": false + AMPAS: { + name: "Academy of Motion Picture Arts and Sciences BSD", + url: "https://fedoraproject.org/wiki/Licensing/BSD#AMPASBSD", + osiApproved: false, }, - "NOSL": { - "name": "Netizen Open Source License", - "url": "http://bits.netizen.com.au/licenses/NOSL/nosl.txt", - "osiApproved": false + NOSL: { + name: "Netizen Open Source License", + url: "http://bits.netizen.com.au/licenses/NOSL/nosl.txt", + osiApproved: false, }, - "fwlw": { - "name": "fwlw License", - "url": "https://mirrors.nic.cz/tex-archive/macros/latex/contrib/fwlw/README", - "osiApproved": false + fwlw: { + name: "fwlw License", + url: "https://mirrors.nic.cz/tex-archive/macros/latex/contrib/fwlw/README", + osiApproved: false, }, - "w3m": { - "name": "w3m License", - "url": "https://github.com/tats/w3m/blob/master/COPYING", - "osiApproved": false + w3m: { + name: "w3m License", + url: "https://github.com/tats/w3m/blob/master/COPYING", + osiApproved: false, }, - "Latex2e": { - "name": "Latex2e License", - "url": "https://fedoraproject.org/wiki/Licensing/Latex2e", - "osiApproved": false + Latex2e: { + name: "Latex2e License", + url: "https://fedoraproject.org/wiki/Licensing/Latex2e", + osiApproved: false, }, "O-UDA-1.0": { - "name": "Open Use of Data Agreement v1.0", - "url": "https://github.com/microsoft/Open-Use-of-Data-Agreement/blob/v1.0/O-UDA-1.0.md", - "osiApproved": false + name: "Open Use of Data Agreement v1.0", + url: "https://github.com/microsoft/Open-Use-of-Data-Agreement/blob/v1.0/O-UDA-1.0.md", + osiApproved: false, }, - "mplus": { - "name": "mplus Font License", - "url": "https://fedoraproject.org/wiki/Licensing:Mplus?rd=Licensing/mplus", - "osiApproved": false + mplus: { + name: "mplus Font License", + url: "https://fedoraproject.org/wiki/Licensing:Mplus?rd=Licensing/mplus", + osiApproved: false, }, "HPND-Intel": { - "name": "Historical Permission Notice and Disclaimer - Intel variant", - "url": "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/machine/i960/memcpy.S;hb=HEAD", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - Intel variant", + url: "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/machine/i960/memcpy.S;hb=HEAD", + osiApproved: false, }, - "PPL": { - "name": "Peer Production License", - "url": "https://wiki.p2pfoundation.net/Peer_Production_License", - "osiApproved": false + PPL: { + name: "Peer Production License", + url: "https://wiki.p2pfoundation.net/Peer_Production_License", + osiApproved: false, }, "OFL-1.1-RFN": { - "name": "SIL Open Font License 1.1 with Reserved Font Name", - "url": "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web", - "osiApproved": true + name: "SIL Open Font License 1.1 with Reserved Font Name", + url: "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web", + osiApproved: true, }, "EPL-1.0": { - "name": "Eclipse Public License 1.0", - "url": "http://www.eclipse.org/legal/epl-v10.html", - "osiApproved": true + name: "Eclipse Public License 1.0", + url: "http://www.eclipse.org/legal/epl-v10.html", + osiApproved: true, }, "HPND-UC-export-US": { - "name": "Historical Permission Notice and Disclaimer - University of California, US export warning", - "url": "https://github.com/RTimothyEdwards/magic/blob/master/LICENSE", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - University of California, US export warning", + url: "https://github.com/RTimothyEdwards/magic/blob/master/LICENSE", + osiApproved: false, }, "CC-BY-3.0-DE": { - "name": "Creative Commons Attribution 3.0 Germany", - "url": "https://creativecommons.org/licenses/by/3.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 Germany", + url: "https://creativecommons.org/licenses/by/3.0/de/legalcode", + osiApproved: false, }, - "SNIA": { - "name": "SNIA Public License 1.1", - "url": "https://fedoraproject.org/wiki/Licensing/SNIA_Public_License", - "osiApproved": false + SNIA: { + name: "SNIA Public License 1.1", + url: "https://fedoraproject.org/wiki/Licensing/SNIA_Public_License", + osiApproved: false, }, - "Barr": { - "name": "Barr License", - "url": "https://fedoraproject.org/wiki/Licensing/Barr", - "osiApproved": false + Barr: { + name: "Barr License", + url: "https://fedoraproject.org/wiki/Licensing/Barr", + osiApproved: false, }, "OLDAP-2.1": { - "name": "Open LDAP Public License v2.1", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=b0d176738e96a0d3b9f85cb51e140a86f21be715", - "osiApproved": false + name: "Open LDAP Public License v2.1", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=b0d176738e96a0d3b9f85cb51e140a86f21be715", + osiApproved: false, }, "CC-BY-ND-4.0": { - "name": "Creative Commons Attribution No Derivatives 4.0 International", - "url": "https://creativecommons.org/licenses/by-nd/4.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution No Derivatives 4.0 International", + url: "https://creativecommons.org/licenses/by-nd/4.0/legalcode", + osiApproved: false, }, - "softSurfer": { - "name": "softSurfer License", - "url": "https://github.com/mm2/Little-CMS/blob/master/src/cmssm.c#L207", - "osiApproved": false + softSurfer: { + name: "softSurfer License", + url: "https://github.com/mm2/Little-CMS/blob/master/src/cmssm.c#L207", + osiApproved: false, }, "LGPL-2.1-or-later": { - "name": "GNU Lesser General Public License v2.1 or later", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v2.1 or later", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", + osiApproved: true, }, "OFL-1.0": { - "name": "SIL Open Font License 1.0", - "url": "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL10_web", - "osiApproved": false + name: "SIL Open Font License 1.0", + url: "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL10_web", + osiApproved: false, }, "BSD-3-Clause-flex": { - "name": "BSD 3-Clause Flex variant", - "url": "https://github.com/westes/flex/blob/master/COPYING", - "osiApproved": false + name: "BSD 3-Clause Flex variant", + url: "https://github.com/westes/flex/blob/master/COPYING", + osiApproved: false, }, - "psfrag": { - "name": "psfrag License", - "url": "https://fedoraproject.org/wiki/Licensing/psfrag", - "osiApproved": false + psfrag: { + name: "psfrag License", + url: "https://fedoraproject.org/wiki/Licensing/psfrag", + osiApproved: false, }, "BSD-1-Clause": { - "name": "BSD 1-Clause License", - "url": "https://svnweb.freebsd.org/base/head/include/ifaddrs.h?revision=326823", - "osiApproved": true + name: "BSD 1-Clause License", + url: "https://svnweb.freebsd.org/base/head/include/ifaddrs.h?revision=326823", + osiApproved: true, }, "BSD-3-Clause-No-Military-License": { - "name": "BSD 3-Clause No Military License", - "url": "https://gitlab.syncad.com/hive/dhive/-/blob/master/LICENSE", - "osiApproved": false + name: "BSD 3-Clause No Military License", + url: "https://gitlab.syncad.com/hive/dhive/-/blob/master/LICENSE", + osiApproved: false, }, - "Cube": { - "name": "Cube License", - "url": "https://fedoraproject.org/wiki/Licensing/Cube", - "osiApproved": false + Cube: { + name: "Cube License", + url: "https://fedoraproject.org/wiki/Licensing/Cube", + osiApproved: false, }, "LPPL-1.2": { - "name": "LaTeX Project Public License v1.2", - "url": "http://www.latex-project.org/lppl/lppl-1-2.txt", - "osiApproved": false + name: "LaTeX Project Public License v1.2", + url: "http://www.latex-project.org/lppl/lppl-1-2.txt", + osiApproved: false, }, "OLDAP-2.2.2": { - "name": "Open LDAP Public License 2.2.2", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=df2cc1e21eb7c160695f5b7cffd6296c151ba188", - "osiApproved": false + name: "Open LDAP Public License 2.2.2", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=df2cc1e21eb7c160695f5b7cffd6296c151ba188", + osiApproved: false, }, - "TTWL": { - "name": "Text-Tabs+Wrap License", - "url": "https://fedoraproject.org/wiki/Licensing/TTWL", - "osiApproved": false + TTWL: { + name: "Text-Tabs+Wrap License", + url: "https://fedoraproject.org/wiki/Licensing/TTWL", + osiApproved: false, }, "CC-BY-3.0": { - "name": "Creative Commons Attribution 3.0 Unported", - "url": "https://creativecommons.org/licenses/by/3.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 Unported", + url: "https://creativecommons.org/licenses/by/3.0/legalcode", + osiApproved: false, }, "BSD-3-Clause-Open-MPI": { - "name": "BSD 3-Clause Open MPI variant", - "url": "https://www.open-mpi.org/community/license.php", - "osiApproved": false + name: "BSD 3-Clause Open MPI variant", + url: "https://www.open-mpi.org/community/license.php", + osiApproved: false, }, "CC-BY-NC-ND-3.0-IGO": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 3.0 IGO", - "url": "https://creativecommons.org/licenses/by-nc-nd/3.0/igo/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 3.0 IGO", + url: "https://creativecommons.org/licenses/by-nc-nd/3.0/igo/legalcode", + osiApproved: false, }, "ZPL-2.1": { - "name": "Zope Public License 2.1", - "url": "http://old.zope.org/Resources/ZPL/", - "osiApproved": true + name: "Zope Public License 2.1", + url: "http://old.zope.org/Resources/ZPL/", + osiApproved: true, }, "CC0-1.0": { - "name": "Creative Commons Zero v1.0 Universal", - "url": "https://creativecommons.org/publicdomain/zero/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Zero v1.0 Universal", + url: "https://creativecommons.org/publicdomain/zero/1.0/legalcode", + osiApproved: false, }, "NPL-1.0": { - "name": "Netscape Public License v1.0", - "url": "http://www.mozilla.org/MPL/NPL/1.0/", - "osiApproved": false + name: "Netscape Public License v1.0", + url: "http://www.mozilla.org/MPL/NPL/1.0/", + osiApproved: false, }, "CECILL-2.0": { - "name": "CeCILL Free Software License Agreement v2.0", - "url": "http://www.cecill.info/licences/Licence_CeCILL_V2-en.html", - "osiApproved": false + name: "CeCILL Free Software License Agreement v2.0", + url: "http://www.cecill.info/licences/Licence_CeCILL_V2-en.html", + osiApproved: false, }, - "wwl": { - "name": "WWL License", - "url": "http://www.db.net/downloads/wwl+db-1.3.tgz", - "osiApproved": false + wwl: { + name: "WWL License", + url: "http://www.db.net/downloads/wwl+db-1.3.tgz", + osiApproved: false, }, - "NGPL": { - "name": "Nethack General Public License", - "url": "https://opensource.org/licenses/NGPL", - "osiApproved": true + NGPL: { + name: "Nethack General Public License", + url: "https://opensource.org/licenses/NGPL", + osiApproved: true, }, - "FSFAP": { - "name": "FSF All Permissive License", - "url": "https://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html", - "osiApproved": false + FSFAP: { + name: "FSF All Permissive License", + url: "https://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html", + osiApproved: false, }, "any-OSI": { - "name": "Any OSI License", - "url": "https://metacpan.org/pod/Exporter::Tidy#LICENSE", - "osiApproved": false + name: "Any OSI License", + url: "https://metacpan.org/pod/Exporter::Tidy#LICENSE", + osiApproved: false, }, - "mpich2": { - "name": "mpich2 License", - "url": "https://fedoraproject.org/wiki/Licensing/MIT", - "osiApproved": false + mpich2: { + name: "mpich2 License", + url: "https://fedoraproject.org/wiki/Licensing/MIT", + osiApproved: false, }, - "EUDatagrid": { - "name": "EU DataGrid Software License", - "url": "http://eu-datagrid.web.cern.ch/eu-datagrid/license.html", - "osiApproved": true + EUDatagrid: { + name: "EU DataGrid Software License", + url: "http://eu-datagrid.web.cern.ch/eu-datagrid/license.html", + osiApproved: true, }, - "Sleepycat": { - "name": "Sleepycat License", - "url": "https://opensource.org/licenses/Sleepycat", - "osiApproved": true + Sleepycat: { + name: "Sleepycat License", + url: "https://opensource.org/licenses/Sleepycat", + osiApproved: true, }, "AFL-3.0": { - "name": "Academic Free License v3.0", - "url": "http://www.rosenlaw.com/AFL3.0.htm", - "osiApproved": true + name: "Academic Free License v3.0", + url: "http://www.rosenlaw.com/AFL3.0.htm", + osiApproved: true, }, "Arphic-1999": { - "name": "Arphic Public License", - "url": "http://ftp.gnu.org/gnu/non-gnu/chinese-fonts-truetype/LICENSE", - "osiApproved": false + name: "Arphic Public License", + url: "http://ftp.gnu.org/gnu/non-gnu/chinese-fonts-truetype/LICENSE", + osiApproved: false, }, "BSD-4-Clause-UC": { - "name": "BSD-4-Clause (University of California-Specific)", - "url": "http://www.freebsd.org/copyright/license.html", - "osiApproved": false + name: "BSD-4-Clause (University of California-Specific)", + url: "http://www.freebsd.org/copyright/license.html", + osiApproved: false, }, - "dtoa": { - "name": "David M. Gay dtoa License", - "url": "https://github.com/SWI-Prolog/swipl-devel/blob/master/src/os/dtoa.c", - "osiApproved": false + dtoa: { + name: "David M. Gay dtoa License", + url: "https://github.com/SWI-Prolog/swipl-devel/blob/master/src/os/dtoa.c", + osiApproved: false, }, "Unicode-DFS-2015": { - "name": "Unicode License Agreement - Data Files and Software (2015)", - "url": "https://web.archive.org/web/20151224134844/http://unicode.org/copyright.html", - "osiApproved": false + name: "Unicode License Agreement - Data Files and Software (2015)", + url: "https://web.archive.org/web/20151224134844/http://unicode.org/copyright.html", + osiApproved: false, }, "TCP-wrappers": { - "name": "TCP Wrappers License", - "url": "http://rc.quest.com/topics/openssh/license.php#tcpwrappers", - "osiApproved": false + name: "TCP Wrappers License", + url: "http://rc.quest.com/topics/openssh/license.php#tcpwrappers", + osiApproved: false, }, "MIT-0": { - "name": "MIT No Attribution", - "url": "https://github.com/aws/mit-0", - "osiApproved": true + name: "MIT No Attribution", + url: "https://github.com/aws/mit-0", + osiApproved: true, }, "SugarCRM-1.1.3": { - "name": "SugarCRM Public License v1.1.3", - "url": "http://www.sugarcrm.com/crm/SPL", - "osiApproved": false + name: "SugarCRM Public License v1.1.3", + url: "http://www.sugarcrm.com/crm/SPL", + osiApproved: false, }, - "iMatix": { - "name": "iMatix Standard Function Library Agreement", - "url": "http://legacy.imatix.com/html/sfl/sfl4.htm#license", - "osiApproved": false + iMatix: { + name: "iMatix Standard Function Library Agreement", + url: "http://legacy.imatix.com/html/sfl/sfl4.htm#license", + osiApproved: false, }, "CC-BY-3.0-AT": { - "name": "Creative Commons Attribution 3.0 Austria", - "url": "https://creativecommons.org/licenses/by/3.0/at/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 Austria", + url: "https://creativecommons.org/licenses/by/3.0/at/legalcode", + osiApproved: false, }, "Adobe-2006": { - "name": "Adobe Systems Incorporated Source Code License Agreement", - "url": "https://fedoraproject.org/wiki/Licensing/AdobeLicense", - "osiApproved": false + name: "Adobe Systems Incorporated Source Code License Agreement", + url: "https://fedoraproject.org/wiki/Licensing/AdobeLicense", + osiApproved: false, }, - "LOOP": { - "name": "Common Lisp LOOP License", - "url": "https://gitlab.com/embeddable-common-lisp/ecl/-/blob/develop/src/lsp/loop.lsp", - "osiApproved": false + LOOP: { + name: "Common Lisp LOOP License", + url: "https://gitlab.com/embeddable-common-lisp/ecl/-/blob/develop/src/lsp/loop.lsp", + osiApproved: false, }, "MIT-testregex": { - "name": "MIT testregex Variant", - "url": "https://github.com/dotnet/runtime/blob/55e1ac7c07df62c4108d4acedf78f77574470ce5/src/libraries/System.Text.RegularExpressions/tests/FunctionalTests/AttRegexTests.cs#L12-L28", - "osiApproved": false + name: "MIT testregex Variant", + url: "https://github.com/dotnet/runtime/blob/55e1ac7c07df62c4108d4acedf78f77574470ce5/src/libraries/System.Text.RegularExpressions/tests/FunctionalTests/AttRegexTests.cs#L12-L28", + osiApproved: false, }, - "eGenix": { - "name": "eGenix.com Public License 1.1.0", - "url": "http://www.egenix.com/products/eGenix.com-Public-License-1.1.0.pdf", - "osiApproved": false + eGenix: { + name: "eGenix.com Public License 1.1.0", + url: "http://www.egenix.com/products/eGenix.com-Public-License-1.1.0.pdf", + osiApproved: false, }, "GCR-docs": { - "name": "Gnome GCR Documentation License", - "url": "https://github.com/GNOME/gcr/blob/master/docs/COPYING", - "osiApproved": false + name: "Gnome GCR Documentation License", + url: "https://github.com/GNOME/gcr/blob/master/docs/COPYING", + osiApproved: false, }, - "AAL": { - "name": "Attribution Assurance License", - "url": "https://opensource.org/licenses/attribution", - "osiApproved": true + AAL: { + name: "Attribution Assurance License", + url: "https://opensource.org/licenses/attribution", + osiApproved: true, }, "CAL-1.0": { - "name": "Cryptographic Autonomy License 1.0", - "url": "http://cryptographicautonomylicense.com/license-text.html", - "osiApproved": true + name: "Cryptographic Autonomy License 1.0", + url: "http://cryptographicautonomylicense.com/license-text.html", + osiApproved: true, }, "PHP-3.0": { - "name": "PHP License v3.0", - "url": "http://www.php.net/license/3_0.txt", - "osiApproved": true + name: "PHP License v3.0", + url: "http://www.php.net/license/3_0.txt", + osiApproved: true, }, - "hdparm": { - "name": "hdparm License", - "url": "https://github.com/Distrotech/hdparm/blob/4517550db29a91420fb2b020349523b1b4512df2/LICENSE.TXT", - "osiApproved": false + hdparm: { + name: "hdparm License", + url: "https://github.com/Distrotech/hdparm/blob/4517550db29a91420fb2b020349523b1b4512df2/LICENSE.TXT", + osiApproved: false, }, "OpenPBS-2.3": { - "name": "OpenPBS v2.3 Software License", - "url": "https://github.com/adaptivecomputing/torque/blob/master/PBS_License.txt", - "osiApproved": false + name: "OpenPBS v2.3 Software License", + url: "https://github.com/adaptivecomputing/torque/blob/master/PBS_License.txt", + osiApproved: false, }, "DL-DE-BY-2.0": { - "name": "Data licence Germany – attribution – version 2.0", - "url": "https://www.govdata.de/dl-de/by-2-0", - "osiApproved": false + name: "Data licence Germany – attribution – version 2.0", + url: "https://www.govdata.de/dl-de/by-2-0", + osiApproved: false, }, "GFDL-1.3-or-later": { - "name": "GNU Free Documentation License v1.3 or later", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3 or later", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, "CERN-OHL-1.2": { - "name": "CERN Open Hardware Licence v1.2", - "url": "https://www.ohwr.org/project/licenses/wikis/cern-ohl-v1.2", - "osiApproved": false + name: "CERN Open Hardware Licence v1.2", + url: "https://www.ohwr.org/project/licenses/wikis/cern-ohl-v1.2", + osiApproved: false, }, - "MIT": { - "name": "MIT License", - "url": "https://opensource.org/license/mit/", - "osiApproved": true + MIT: { + name: "MIT License", + url: "https://opensource.org/license/mit/", + osiApproved: true, }, - "XSkat": { - "name": "XSkat License", - "url": "https://fedoraproject.org/wiki/Licensing/XSkat_License", - "osiApproved": false + XSkat: { + name: "XSkat License", + url: "https://fedoraproject.org/wiki/Licensing/XSkat_License", + osiApproved: false, }, - "Gutmann": { - "name": "Gutmann License", - "url": "https://www.cs.auckland.ac.nz/~pgut001/dumpasn1.c", - "osiApproved": false + Gutmann: { + name: "Gutmann License", + url: "https://www.cs.auckland.ac.nz/~pgut001/dumpasn1.c", + osiApproved: false, }, - "wxWindows": { - "name": "wxWindows Library License", - "url": "https://opensource.org/licenses/WXwindows", - "osiApproved": true + wxWindows: { + name: "wxWindows Library License", + url: "https://opensource.org/licenses/WXwindows", + osiApproved: true, }, "CC-BY-NC-SA-2.5": { - "name": "Creative Commons Attribution Non Commercial Share Alike 2.5 Generic", - "url": "https://creativecommons.org/licenses/by-nc-sa/2.5/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 2.5 Generic", + url: "https://creativecommons.org/licenses/by-nc-sa/2.5/legalcode", + osiApproved: false, }, "PDDL-1.0": { - "name": "Open Data Commons Public Domain Dedication & License 1.0", - "url": "http://opendatacommons.org/licenses/pddl/1.0/", - "osiApproved": false + name: "Open Data Commons Public Domain Dedication & License 1.0", + url: "http://opendatacommons.org/licenses/pddl/1.0/", + osiApproved: false, }, - "Unlicense": { - "name": "The Unlicense", - "url": "https://unlicense.org/", - "osiApproved": true + Unlicense: { + name: "The Unlicense", + url: "https://unlicense.org/", + osiApproved: true, }, "CUA-OPL-1.0": { - "name": "CUA Office Public License v1.0", - "url": "https://opensource.org/licenses/CUA-OPL-1.0", - "osiApproved": true + name: "CUA Office Public License v1.0", + url: "https://opensource.org/licenses/CUA-OPL-1.0", + osiApproved: true, }, - "NCL": { - "name": "NCL Source Code License", - "url": "https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-filter-chain/pffft.c?ref_type=heads#L1-52", - "osiApproved": false + NCL: { + name: "NCL Source Code License", + url: "https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-filter-chain/pffft.c?ref_type=heads#L1-52", + osiApproved: false, }, "GFDL-1.1-invariants-or-later": { - "name": "GNU Free Documentation License v1.1 or later - invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1 or later - invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, "CECILL-2.1": { - "name": "CeCILL Free Software License Agreement v2.1", - "url": "http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html", - "osiApproved": true + name: "CeCILL Free Software License Agreement v2.1", + url: "http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html", + osiApproved: true, }, "PolyForm-Small-Business-1.0.0": { - "name": "PolyForm Small Business License 1.0.0", - "url": "https://polyformproject.org/licenses/small-business/1.0.0", - "osiApproved": false + name: "PolyForm Small Business License 1.0.0", + url: "https://polyformproject.org/licenses/small-business/1.0.0", + osiApproved: false, }, "HP-1986": { - "name": "Hewlett-Packard 1986 License", - "url": "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/machine/hppa/memchr.S;h=1cca3e5e8867aa4bffef1f75a5c1bba25c0c441e;hb=HEAD#l2", - "osiApproved": false + name: "Hewlett-Packard 1986 License", + url: "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/machine/hppa/memchr.S;h=1cca3e5e8867aa4bffef1f75a5c1bba25c0c441e;hb=HEAD#l2", + osiApproved: false, }, "HPND-export-US": { - "name": "HPND with US Government export control warning", - "url": "https://www.kermitproject.org/ck90.html#source", - "osiApproved": false + name: "HPND with US Government export control warning", + url: "https://www.kermitproject.org/ck90.html#source", + osiApproved: false, }, "X11-swapped": { - "name": "X11 swapped final paragraphs", - "url": "https://github.com/fedeinthemix/chez-srfi/blob/master/srfi/LICENSE", - "osiApproved": false + name: "X11 swapped final paragraphs", + url: "https://github.com/fedeinthemix/chez-srfi/blob/master/srfi/LICENSE", + osiApproved: false, }, "SHL-0.5": { - "name": "Solderpad Hardware License v0.5", - "url": "https://solderpad.org/licenses/SHL-0.5/", - "osiApproved": false + name: "Solderpad Hardware License v0.5", + url: "https://solderpad.org/licenses/SHL-0.5/", + osiApproved: false, }, "BSD-Systemics": { - "name": "Systemics BSD variant license", - "url": "https://metacpan.org/release/DPARIS/Crypt-DES-2.07/source/COPYRIGHT", - "osiApproved": false + name: "Systemics BSD variant license", + url: "https://metacpan.org/release/DPARIS/Crypt-DES-2.07/source/COPYRIGHT", + osiApproved: false, }, "CDLA-Sharing-1.0": { - "name": "Community Data License Agreement Sharing 1.0", - "url": "https://cdla.io/sharing-1-0", - "osiApproved": false + name: "Community Data License Agreement Sharing 1.0", + url: "https://cdla.io/sharing-1-0", + osiApproved: false, }, "GFDL-1.1-or-later": { - "name": "GNU Free Documentation License v1.1 or later", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1 or later", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, - "Newsletr": { - "name": "Newsletr License", - "url": "https://fedoraproject.org/wiki/Licensing/Newsletr", - "osiApproved": false + Newsletr: { + name: "Newsletr License", + url: "https://fedoraproject.org/wiki/Licensing/Newsletr", + osiApproved: false, }, - "TMate": { - "name": "TMate Open Source License", - "url": "http://svnkit.com/license.html", - "osiApproved": false + TMate: { + name: "TMate Open Source License", + url: "http://svnkit.com/license.html", + osiApproved: false, }, - "EPICS": { - "name": "EPICS Open License", - "url": "https://epics.anl.gov/license/open.php", - "osiApproved": false + EPICS: { + name: "EPICS Open License", + url: "https://epics.anl.gov/license/open.php", + osiApproved: false, }, "SAX-PD": { - "name": "Sax Public Domain Notice", - "url": "http://www.saxproject.org/copying.html", - "osiApproved": false + name: "Sax Public Domain Notice", + url: "http://www.saxproject.org/copying.html", + osiApproved: false, }, "MIT-Festival": { - "name": "MIT Festival Variant", - "url": "https://github.com/festvox/flite/blob/master/COPYING", - "osiApproved": false + name: "MIT Festival Variant", + url: "https://github.com/festvox/flite/blob/master/COPYING", + osiApproved: false, }, "LGPL-2.0-or-later": { - "name": "GNU Library General Public License v2 or later", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", - "osiApproved": true + name: "GNU Library General Public License v2 or later", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", + osiApproved: true, }, "QPL-1.0": { - "name": "Q Public License 1.0", - "url": "http://doc.qt.nokia.com/3.3/license.html", - "osiApproved": true + name: "Q Public License 1.0", + url: "http://doc.qt.nokia.com/3.3/license.html", + osiApproved: true, }, "SSH-short": { - "name": "SSH short notice", - "url": "https://github.com/openssh/openssh-portable/blob/1b11ea7c58cd5c59838b5fa574cd456d6047b2d4/pathnames.h", - "osiApproved": false + name: "SSH short notice", + url: "https://github.com/openssh/openssh-portable/blob/1b11ea7c58cd5c59838b5fa574cd456d6047b2d4/pathnames.h", + osiApproved: false, }, "OGL-UK-1.0": { - "name": "Open Government Licence v1.0", - "url": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/1/", - "osiApproved": false + name: "Open Government Licence v1.0", + url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/1/", + osiApproved: false, }, "GPL-2.0-only": { - "name": "GNU General Public License v2.0 only", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v2.0 only", + url: "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", + osiApproved: true, }, "GPL-3.0-with-GCC-exception": { - "name": "GNU General Public License v3.0 w/GCC Runtime Library exception", - "url": "https://www.gnu.org/licenses/gcc-exception-3.1.html", - "osiApproved": true + name: "GNU General Public License v3.0 w/GCC Runtime Library exception", + url: "https://www.gnu.org/licenses/gcc-exception-3.1.html", + osiApproved: true, }, "ECL-2.0": { - "name": "Educational Community License v2.0", - "url": "https://opensource.org/licenses/ECL-2.0", - "osiApproved": true + name: "Educational Community License v2.0", + url: "https://opensource.org/licenses/ECL-2.0", + osiApproved: true, }, "CATOSL-1.1": { - "name": "Computer Associates Trusted Open Source License 1.1", - "url": "https://opensource.org/licenses/CATOSL-1.1", - "osiApproved": true + name: "Computer Associates Trusted Open Source License 1.1", + url: "https://opensource.org/licenses/CATOSL-1.1", + osiApproved: true, }, "Cornell-Lossless-JPEG": { - "name": "Cornell Lossless JPEG License", - "url": "https://android.googlesource.com/platform/external/dng_sdk/+/refs/heads/master/source/dng_lossless_jpeg.cpp#16", - "osiApproved": false + name: "Cornell Lossless JPEG License", + url: "https://android.googlesource.com/platform/external/dng_sdk/+/refs/heads/master/source/dng_lossless_jpeg.cpp#16", + osiApproved: false, }, - "DOC": { - "name": "DOC License", - "url": "http://www.cs.wustl.edu/~schmidt/ACE-copying.html", - "osiApproved": false + DOC: { + name: "DOC License", + url: "http://www.cs.wustl.edu/~schmidt/ACE-copying.html", + osiApproved: false, }, "RSA-MD": { - "name": "RSA Message-Digest License", - "url": "http://www.faqs.org/rfcs/rfc1321.html", - "osiApproved": false + name: "RSA Message-Digest License", + url: "http://www.faqs.org/rfcs/rfc1321.html", + osiApproved: false, }, "OCLC-2.0": { - "name": "OCLC Research Public License 2.0", - "url": "http://www.oclc.org/research/activities/software/license/v2final.htm", - "osiApproved": true + name: "OCLC Research Public License 2.0", + url: "http://www.oclc.org/research/activities/software/license/v2final.htm", + osiApproved: true, }, "AGPL-3.0-only": { - "name": "GNU Affero General Public License v3.0 only", - "url": "https://www.gnu.org/licenses/agpl.txt", - "osiApproved": true + name: "GNU Affero General Public License v3.0 only", + url: "https://www.gnu.org/licenses/agpl.txt", + osiApproved: true, }, "OLDAP-2.5": { - "name": "Open LDAP Public License v2.5", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=6852b9d90022e8593c98205413380536b1b5a7cf", - "osiApproved": false + name: "Open LDAP Public License v2.5", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=6852b9d90022e8593c98205413380536b1b5a7cf", + osiApproved: false, }, "CC-BY-SA-3.0-DE": { - "name": "Creative Commons Attribution Share Alike 3.0 Germany", - "url": "https://creativecommons.org/licenses/by-sa/3.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 3.0 Germany", + url: "https://creativecommons.org/licenses/by-sa/3.0/de/legalcode", + osiApproved: false, }, "Artistic-1.0-Perl": { - "name": "Artistic License 1.0 (Perl)", - "url": "http://dev.perl.org/licenses/artistic.html", - "osiApproved": true + name: "Artistic License 1.0 (Perl)", + url: "http://dev.perl.org/licenses/artistic.html", + osiApproved: true, }, "CC-BY-NC-ND-4.0": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 4.0 International", - "url": "https://creativecommons.org/licenses/by-nc-nd/4.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 4.0 International", + url: "https://creativecommons.org/licenses/by-nc-nd/4.0/legalcode", + osiApproved: false, }, "BSD-3-Clause-No-Nuclear-License-2014": { - "name": "BSD 3-Clause No Nuclear License 2014", - "url": "https://java.net/projects/javaeetutorial/pages/BerkeleyLicense", - "osiApproved": false + name: "BSD 3-Clause No Nuclear License 2014", + url: "https://java.net/projects/javaeetutorial/pages/BerkeleyLicense", + osiApproved: false, }, "Martin-Birgmeier": { - "name": "Martin Birgmeier License", - "url": "https://github.com/Perl/perl5/blob/blead/util.c#L6136", - "osiApproved": false + name: "Martin Birgmeier License", + url: "https://github.com/Perl/perl5/blob/blead/util.c#L6136", + osiApproved: false, }, "EUPL-1.0": { - "name": "European Union Public License 1.0", - "url": "http://ec.europa.eu/idabc/en/document/7330.html", - "osiApproved": false + name: "European Union Public License 1.0", + url: "http://ec.europa.eu/idabc/en/document/7330.html", + osiApproved: false, }, "GPL-2.0": { - "name": "GNU General Public License v2.0 only", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v2.0 only", + url: "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", + osiApproved: true, }, "McPhee-slideshow": { - "name": "McPhee Slideshow License", - "url": "https://mirror.las.iastate.edu/tex-archive/graphics/metapost/contrib/macros/slideshow/slideshow.mp", - "osiApproved": false + name: "McPhee Slideshow License", + url: "https://mirror.las.iastate.edu/tex-archive/graphics/metapost/contrib/macros/slideshow/slideshow.mp", + osiApproved: false, }, "CC-BY-NC-ND-1.0": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 1.0 Generic", - "url": "https://creativecommons.org/licenses/by-nd-nc/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 1.0 Generic", + url: "https://creativecommons.org/licenses/by-nd-nc/1.0/legalcode", + osiApproved: false, }, "BlueOak-1.0.0": { - "name": "Blue Oak Model License 1.0.0", - "url": "https://blueoakcouncil.org/license/1.0.0", - "osiApproved": true + name: "Blue Oak Model License 1.0.0", + url: "https://blueoakcouncil.org/license/1.0.0", + osiApproved: true, }, "ODC-By-1.0": { - "name": "Open Data Commons Attribution License v1.0", - "url": "https://opendatacommons.org/licenses/by/1.0/", - "osiApproved": false + name: "Open Data Commons Attribution License v1.0", + url: "https://opendatacommons.org/licenses/by/1.0/", + osiApproved: false, }, "COIL-1.0": { - "name": "Copyfree Open Innovation License", - "url": "https://coil.apotheon.org/plaintext/01.0.txt", - "osiApproved": false + name: "Copyfree Open Innovation License", + url: "https://coil.apotheon.org/plaintext/01.0.txt", + osiApproved: false, }, "Bitstream-Vera": { - "name": "Bitstream Vera Font License", - "url": "https://web.archive.org/web/20080207013128/http://www.gnome.org/fonts/", - "osiApproved": false + name: "Bitstream Vera Font License", + url: "https://web.archive.org/web/20080207013128/http://www.gnome.org/fonts/", + osiApproved: false, }, "JPL-image": { - "name": "JPL Image Use Policy", - "url": "https://www.jpl.nasa.gov/jpl-image-use-policy", - "osiApproved": false + name: "JPL Image Use Policy", + url: "https://www.jpl.nasa.gov/jpl-image-use-policy", + osiApproved: false, }, "MIT-enna": { - "name": "enna License", - "url": "https://fedoraproject.org/wiki/Licensing/MIT#enna", - "osiApproved": false + name: "enna License", + url: "https://fedoraproject.org/wiki/Licensing/MIT#enna", + osiApproved: false, }, "BSD-Inferno-Nettverk": { - "name": "BSD-Inferno-Nettverk", - "url": "https://www.inet.no/dante/LICENSE", - "osiApproved": false + name: "BSD-Inferno-Nettverk", + url: "https://www.inet.no/dante/LICENSE", + osiApproved: false, }, "CDDL-1.1": { - "name": "Common Development and Distribution License 1.1", - "url": "http://glassfish.java.net/public/CDDL+GPL_1_1.html", - "osiApproved": false + name: "Common Development and Distribution License 1.1", + url: "http://glassfish.java.net/public/CDDL+GPL_1_1.html", + osiApproved: false, }, - "FSFULLRWD": { - "name": "FSF Unlimited License (With License Retention and Warranty Disclaimer)", - "url": "https://lists.gnu.org/archive/html/autoconf/2012-04/msg00061.html", - "osiApproved": false + FSFULLRWD: { + name: "FSF Unlimited License (With License Retention and Warranty Disclaimer)", + url: "https://lists.gnu.org/archive/html/autoconf/2012-04/msg00061.html", + osiApproved: false, }, "GFDL-1.2-invariants-only": { - "name": "GNU Free Documentation License v1.2 only - invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2 only - invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, "EFL-1.0": { - "name": "Eiffel Forum License v1.0", - "url": "http://www.eiffel-nice.org/license/forum.txt", - "osiApproved": true + name: "Eiffel Forum License v1.0", + url: "http://www.eiffel-nice.org/license/forum.txt", + osiApproved: true, }, - "Entessa": { - "name": "Entessa Public License v1.0", - "url": "https://opensource.org/licenses/Entessa", - "osiApproved": true + Entessa: { + name: "Entessa Public License v1.0", + url: "https://opensource.org/licenses/Entessa", + osiApproved: true, }, - "Glide": { - "name": "3dfx Glide License", - "url": "http://www.users.on.net/~triforce/glidexp/COPYING.txt", - "osiApproved": false + Glide: { + name: "3dfx Glide License", + url: "http://www.users.on.net/~triforce/glidexp/COPYING.txt", + osiApproved: false, }, "CC-BY-NC-3.0-DE": { - "name": "Creative Commons Attribution Non Commercial 3.0 Germany", - "url": "https://creativecommons.org/licenses/by-nc/3.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial 3.0 Germany", + url: "https://creativecommons.org/licenses/by-nc/3.0/de/legalcode", + osiApproved: false, }, "Artistic-1.0-cl8": { - "name": "Artistic License 1.0 w/clause 8", - "url": "https://opensource.org/licenses/Artistic-1.0", - "osiApproved": true + name: "Artistic License 1.0 w/clause 8", + url: "https://opensource.org/licenses/Artistic-1.0", + osiApproved: true, }, "W3C-19980720": { - "name": "W3C Software Notice and License (1998-07-20)", - "url": "http://www.w3.org/Consortium/Legal/copyright-software-19980720.html", - "osiApproved": false + name: "W3C Software Notice and License (1998-07-20)", + url: "http://www.w3.org/Consortium/Legal/copyright-software-19980720.html", + osiApproved: false, }, "HPND-merchantability-variant": { - "name": "Historical Permission Notice and Disclaimer - merchantability variant", - "url": "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/misc/fini.c;hb=HEAD", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - merchantability variant", + url: "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/misc/fini.c;hb=HEAD", + osiApproved: false, }, - "Motosoto": { - "name": "Motosoto License", - "url": "https://opensource.org/licenses/Motosoto", - "osiApproved": true + Motosoto: { + name: "Motosoto License", + url: "https://opensource.org/licenses/Motosoto", + osiApproved: true, }, "OLDAP-1.1": { - "name": "Open LDAP Public License v1.1", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=806557a5ad59804ef3a44d5abfbe91d706b0791f", - "osiApproved": false + name: "Open LDAP Public License v1.1", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=806557a5ad59804ef3a44d5abfbe91d706b0791f", + osiApproved: false, }, "HP-1989": { - "name": "Hewlett-Packard 1989 License", - "url": "https://github.com/bleargh45/Data-UUID/blob/master/LICENSE", - "osiApproved": false + name: "Hewlett-Packard 1989 License", + url: "https://github.com/bleargh45/Data-UUID/blob/master/LICENSE", + osiApproved: false, }, "IEC-Code-Components-EULA": { - "name": "IEC Code Components End-user licence agreement", - "url": "https://www.iec.ch/webstore/custserv/pdf/CC-EULA.pdf", - "osiApproved": false + name: "IEC Code Components End-user licence agreement", + url: "https://www.iec.ch/webstore/custserv/pdf/CC-EULA.pdf", + osiApproved: false, }, "NCGL-UK-2.0": { - "name": "Non-Commercial Government Licence", - "url": "http://www.nationalarchives.gov.uk/doc/non-commercial-government-licence/version/2/", - "osiApproved": false + name: "Non-Commercial Government Licence", + url: "http://www.nationalarchives.gov.uk/doc/non-commercial-government-licence/version/2/", + osiApproved: false, }, "CC-BY-3.0-IGO": { - "name": "Creative Commons Attribution 3.0 IGO", - "url": "https://creativecommons.org/licenses/by/3.0/igo/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 IGO", + url: "https://creativecommons.org/licenses/by/3.0/igo/legalcode", + osiApproved: false, }, "BSD-Source-Code": { - "name": "BSD Source Code Attribution", - "url": "https://github.com/robbiehanson/CocoaHTTPServer/blob/master/LICENSE.txt", - "osiApproved": false + name: "BSD Source Code Attribution", + url: "https://github.com/robbiehanson/CocoaHTTPServer/blob/master/LICENSE.txt", + osiApproved: false, }, "GFDL-1.1-no-invariants-only": { - "name": "GNU Free Documentation License v1.1 only - no invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1 only - no invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, - "W3C": { - "name": "W3C Software Notice and License (2002-12-31)", - "url": "http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html", - "osiApproved": true + W3C: { + name: "W3C Software Notice and License (2002-12-31)", + url: "http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html", + osiApproved: true, }, - "magaz": { - "name": "magaz License", - "url": "https://mirrors.nic.cz/tex-archive/macros/latex/contrib/magaz/magaz.tex", - "osiApproved": false + magaz: { + name: "magaz License", + url: "https://mirrors.nic.cz/tex-archive/macros/latex/contrib/magaz/magaz.tex", + osiApproved: false, }, "libutil-David-Nugent": { - "name": "libutil David Nugent License", - "url": "http://web.mit.edu/freebsd/head/lib/libutil/login_ok.3", - "osiApproved": false + name: "libutil David Nugent License", + url: "http://web.mit.edu/freebsd/head/lib/libutil/login_ok.3", + osiApproved: false, }, "AFL-2.1": { - "name": "Academic Free License v2.1", - "url": "http://opensource.linux-mirror.org/licenses/afl-2.1.txt", - "osiApproved": true + name: "Academic Free License v2.1", + url: "http://opensource.linux-mirror.org/licenses/afl-2.1.txt", + osiApproved: true, }, "NAIST-2003": { - "name": "Nara Institute of Science and Technology License (2003)", - "url": "https://enterprise.dejacode.com/licenses/public/naist-2003/#license-text", - "osiApproved": false + name: "Nara Institute of Science and Technology License (2003)", + url: "https://enterprise.dejacode.com/licenses/public/naist-2003/#license-text", + osiApproved: false, }, "DocBook-XML": { - "name": "DocBook XML License", - "url": "https://github.com/docbook/xslt10-stylesheets/blob/efd62655c11cc8773708df7a843613fa1e932bf8/xsl/COPYING#L27", - "osiApproved": false + name: "DocBook XML License", + url: "https://github.com/docbook/xslt10-stylesheets/blob/efd62655c11cc8773708df7a843613fa1e932bf8/xsl/COPYING#L27", + osiApproved: false, }, "LiLiQ-Rplus-1.1": { - "name": "Licence Libre du Québec – Réciprocité forte version 1.1", - "url": "https://www.forge.gouv.qc.ca/participez/licence-logicielle/licence-libre-du-quebec-liliq-en-francais/licence-libre-du-quebec-reciprocite-forte-liliq-r-v1-1/", - "osiApproved": true + name: "Licence Libre du Québec – Réciprocité forte version 1.1", + url: "https://www.forge.gouv.qc.ca/participez/licence-logicielle/licence-libre-du-quebec-liliq-en-francais/licence-libre-du-quebec-reciprocite-forte-liliq-r-v1-1/", + osiApproved: true, }, "MIT-feh": { - "name": "feh License", - "url": "https://fedoraproject.org/wiki/Licensing/MIT#feh", - "osiApproved": false + name: "feh License", + url: "https://fedoraproject.org/wiki/Licensing/MIT#feh", + osiApproved: false, }, "LGPL-2.1": { - "name": "GNU Lesser General Public License v2.1 only", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v2.1 only", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", + osiApproved: true, }, "UMich-Merit": { - "name": "Michigan/Merit Networks License", - "url": "https://github.com/radcli/radcli/blob/master/COPYRIGHT#L64", - "osiApproved": false + name: "Michigan/Merit Networks License", + url: "https://github.com/radcli/radcli/blob/master/COPYRIGHT#L64", + osiApproved: false, }, "CC-BY-NC-3.0": { - "name": "Creative Commons Attribution Non Commercial 3.0 Unported", - "url": "https://creativecommons.org/licenses/by-nc/3.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial 3.0 Unported", + url: "https://creativecommons.org/licenses/by-nc/3.0/legalcode", + osiApproved: false, }, "GPL-1.0": { - "name": "GNU General Public License v1.0 only", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", - "osiApproved": false + name: "GNU General Public License v1.0 only", + url: "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", + osiApproved: false, }, - "NTP": { - "name": "NTP License", - "url": "https://opensource.org/licenses/NTP", - "osiApproved": true + NTP: { + name: "NTP License", + url: "https://opensource.org/licenses/NTP", + osiApproved: true, }, "Frameworx-1.0": { - "name": "Frameworx Open License 1.0", - "url": "https://opensource.org/licenses/Frameworx-1.0", - "osiApproved": true + name: "Frameworx Open License 1.0", + url: "https://opensource.org/licenses/Frameworx-1.0", + osiApproved: true, }, "BSD-2-Clause-NetBSD": { - "name": "BSD 2-Clause NetBSD License", - "url": "http://www.netbsd.org/about/redistribution.html#default", - "osiApproved": false + name: "BSD 2-Clause NetBSD License", + url: "http://www.netbsd.org/about/redistribution.html#default", + osiApproved: false, }, "HPND-sell-variant": { - "name": "Historical Permission Notice and Disclaimer - sell variant", - "url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/net/sunrpc/auth_gss/gss_generic_token.c?h=v4.19", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - sell variant", + url: "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/net/sunrpc/auth_gss/gss_generic_token.c?h=v4.19", + osiApproved: false, }, "CC-BY-1.0": { - "name": "Creative Commons Attribution 1.0 Generic", - "url": "https://creativecommons.org/licenses/by/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 1.0 Generic", + url: "https://creativecommons.org/licenses/by/1.0/legalcode", + osiApproved: false, }, "APL-1.0": { - "name": "Adaptive Public License 1.0", - "url": "https://opensource.org/licenses/APL-1.0", - "osiApproved": true + name: "Adaptive Public License 1.0", + url: "https://opensource.org/licenses/APL-1.0", + osiApproved: true, }, - "WTFPL": { - "name": "Do What The F*ck You Want To Public License", - "url": "http://www.wtfpl.net/about/", - "osiApproved": false + WTFPL: { + name: "Do What The F*ck You Want To Public License", + url: "http://www.wtfpl.net/about/", + osiApproved: false, }, - "FBM": { - "name": "Fuzzy Bitmap License", - "url": "https://github.com/SWI-Prolog/packages-xpce/blob/161a40cd82004f731ba48024f9d30af388a7edf5/src/img/gifwrite.c#L21-L26", - "osiApproved": false + FBM: { + name: "Fuzzy Bitmap License", + url: "https://github.com/SWI-Prolog/packages-xpce/blob/161a40cd82004f731ba48024f9d30af388a7edf5/src/img/gifwrite.c#L21-L26", + osiApproved: false, }, - "ClArtistic": { - "name": "Clarified Artistic License", - "url": "http://gianluca.dellavedova.org/2011/01/03/clarified-artistic-license/", - "osiApproved": false + ClArtistic: { + name: "Clarified Artistic License", + url: "http://gianluca.dellavedova.org/2011/01/03/clarified-artistic-license/", + osiApproved: false, }, - "SunPro": { - "name": "SunPro License", - "url": "https://github.com/freebsd/freebsd-src/blob/main/lib/msun/src/e_acosh.c", - "osiApproved": false + SunPro: { + name: "SunPro License", + url: "https://github.com/freebsd/freebsd-src/blob/main/lib/msun/src/e_acosh.c", + osiApproved: false, }, "VSL-1.0": { - "name": "Vovida Software License v1.0", - "url": "https://opensource.org/licenses/VSL-1.0", - "osiApproved": true + name: "Vovida Software License v1.0", + url: "https://opensource.org/licenses/VSL-1.0", + osiApproved: true, }, "CC-BY-NC-SA-3.0-IGO": { - "name": "Creative Commons Attribution Non Commercial Share Alike 3.0 IGO", - "url": "https://creativecommons.org/licenses/by-nc-sa/3.0/igo/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 3.0 IGO", + url: "https://creativecommons.org/licenses/by-nc-sa/3.0/igo/legalcode", + osiApproved: false, }, "NBPL-1.0": { - "name": "Net Boolean Public License v1", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=37b4b3f6cc4bf34e1d3dec61e69914b9819d8894", - "osiApproved": false + name: "Net Boolean Public License v1", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=37b4b3f6cc4bf34e1d3dec61e69914b9819d8894", + osiApproved: false, }, "OPUBL-1.0": { - "name": "Open Publication License v1.0", - "url": "http://opencontent.org/openpub/", - "osiApproved": false + name: "Open Publication License v1.0", + url: "http://opencontent.org/openpub/", + osiApproved: false, }, "CC-BY-NC-ND-2.0": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 2.0 Generic", - "url": "https://creativecommons.org/licenses/by-nc-nd/2.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 2.0 Generic", + url: "https://creativecommons.org/licenses/by-nc-nd/2.0/legalcode", + osiApproved: false, }, "BSD-3-Clause-LBNL": { - "name": "Lawrence Berkeley National Labs BSD variant license", - "url": "https://fedoraproject.org/wiki/Licensing/LBNLBSD", - "osiApproved": true + name: "Lawrence Berkeley National Labs BSD variant license", + url: "https://fedoraproject.org/wiki/Licensing/LBNLBSD", + osiApproved: true, }, - "Ruby": { - "name": "Ruby License", - "url": "https://www.ruby-lang.org/en/about/license.txt", - "osiApproved": false + Ruby: { + name: "Ruby License", + url: "https://www.ruby-lang.org/en/about/license.txt", + osiApproved: false, }, - "Fair": { - "name": "Fair License", - "url": "https://web.archive.org/web/20150926120323/http://fairlicense.org/", - "osiApproved": true + Fair: { + name: "Fair License", + url: "https://web.archive.org/web/20150926120323/http://fairlicense.org/", + osiApproved: true, }, "MIT-advertising": { - "name": "Enlightenment License (e16)", - "url": "https://fedoraproject.org/wiki/Licensing/MIT_With_Advertising", - "osiApproved": false + name: "Enlightenment License (e16)", + url: "https://fedoraproject.org/wiki/Licensing/MIT_With_Advertising", + osiApproved: false, }, "OGDL-Taiwan-1.0": { - "name": "Taiwan Open Government Data License, version 1.0", - "url": "https://data.gov.tw/license", - "osiApproved": false + name: "Taiwan Open Government Data License, version 1.0", + url: "https://data.gov.tw/license", + osiApproved: false, }, "OPL-UK-3.0": { - "name": "United Kingdom Open Parliament Licence v3.0", - "url": "https://www.parliament.uk/site-information/copyright-parliament/open-parliament-licence/", - "osiApproved": false + name: "United Kingdom Open Parliament Licence v3.0", + url: "https://www.parliament.uk/site-information/copyright-parliament/open-parliament-licence/", + osiApproved: false, }, "MPL-2.0": { - "name": "Mozilla Public License 2.0", - "url": "https://www.mozilla.org/MPL/2.0/", - "osiApproved": true + name: "Mozilla Public License 2.0", + url: "https://www.mozilla.org/MPL/2.0/", + osiApproved: true, }, "DocBook-Stylesheet": { - "name": "DocBook Stylesheet License", - "url": "http://www.docbook.org/xml/5.0/docbook-5.0.zip", - "osiApproved": false + name: "DocBook Stylesheet License", + url: "http://www.docbook.org/xml/5.0/docbook-5.0.zip", + osiApproved: false, }, "TPL-1.0": { - "name": "THOR Public License 1.0", - "url": "https://fedoraproject.org/wiki/Licensing:ThorPublicLicense", - "osiApproved": false + name: "THOR Public License 1.0", + url: "https://fedoraproject.org/wiki/Licensing:ThorPublicLicense", + osiApproved: false, }, "TAPR-OHL-1.0": { - "name": "TAPR Open Hardware License v1.0", - "url": "https://www.tapr.org/OHL", - "osiApproved": false + name: "TAPR Open Hardware License v1.0", + url: "https://www.tapr.org/OHL", + osiApproved: false, }, - "UnixCrypt": { - "name": "UnixCrypt License", - "url": "https://foss.heptapod.net/python-libs/passlib/-/blob/branch/stable/LICENSE#L70", - "osiApproved": false + UnixCrypt: { + name: "UnixCrypt License", + url: "https://foss.heptapod.net/python-libs/passlib/-/blob/branch/stable/LICENSE#L70", + osiApproved: false, }, "FreeBSD-DOC": { - "name": "FreeBSD Documentation License", - "url": "https://www.freebsd.org/copyright/freebsd-doc-license/", - "osiApproved": false + name: "FreeBSD Documentation License", + url: "https://www.freebsd.org/copyright/freebsd-doc-license/", + osiApproved: false, }, "CMU-Mach-nodoc": { - "name": "CMU Mach - no notices-in-documentation variant", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L718-L728", - "osiApproved": false + name: "CMU Mach - no notices-in-documentation variant", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L718-L728", + osiApproved: false, }, "CC-BY-3.0-AU": { - "name": "Creative Commons Attribution 3.0 Australia", - "url": "https://creativecommons.org/licenses/by/3.0/au/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 Australia", + url: "https://creativecommons.org/licenses/by/3.0/au/legalcode", + osiApproved: false, }, "Zimbra-1.4": { - "name": "Zimbra Public License v1.4", - "url": "http://www.zimbra.com/legal/zimbra-public-license-1-4", - "osiApproved": false + name: "Zimbra Public License v1.4", + url: "http://www.zimbra.com/legal/zimbra-public-license-1-4", + osiApproved: false, }, "BSD-3-Clause": { - "name": "BSD 3-Clause \"New\" or \"Revised\" License", - "url": "https://opensource.org/licenses/BSD-3-Clause", - "osiApproved": true + name: 'BSD 3-Clause "New" or "Revised" License', + url: "https://opensource.org/licenses/BSD-3-Clause", + osiApproved: true, }, - "lsof": { - "name": "lsof License", - "url": "https://github.com/lsof-org/lsof/blob/master/COPYING", - "osiApproved": false + lsof: { + name: "lsof License", + url: "https://github.com/lsof-org/lsof/blob/master/COPYING", + osiApproved: false, }, - "FreeImage": { - "name": "FreeImage Public License v1.0", - "url": "http://freeimage.sourceforge.net/freeimage-license.txt", - "osiApproved": false + FreeImage: { + name: "FreeImage Public License v1.0", + url: "http://freeimage.sourceforge.net/freeimage-license.txt", + osiApproved: false, }, "OLDAP-2.0": { - "name": "Open LDAP Public License v2.0 (or possibly 2.0A and 2.0B)", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=cbf50f4e1185a21abd4c0a54d3f4341fe28f36ea", - "osiApproved": false + name: "Open LDAP Public License v2.0 (or possibly 2.0A and 2.0B)", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=cbf50f4e1185a21abd4c0a54d3f4341fe28f36ea", + osiApproved: false, }, "APSL-1.2": { - "name": "Apple Public Source License 1.2", - "url": "http://www.samurajdata.se/opensource/mirror/licenses/apsl.php", - "osiApproved": true + name: "Apple Public Source License 1.2", + url: "http://www.samurajdata.se/opensource/mirror/licenses/apsl.php", + osiApproved: true, }, "APSL-1.0": { - "name": "Apple Public Source License 1.0", - "url": "https://fedoraproject.org/wiki/Licensing/Apple_Public_Source_License_1.0", - "osiApproved": true + name: "Apple Public Source License 1.0", + url: "https://fedoraproject.org/wiki/Licensing/Apple_Public_Source_License_1.0", + osiApproved: true, }, "CC-BY-NC-SA-2.0-FR": { - "name": "Creative Commons Attribution-NonCommercial-ShareAlike 2.0 France", - "url": "https://creativecommons.org/licenses/by-nc-sa/2.0/fr/legalcode", - "osiApproved": false + name: "Creative Commons Attribution-NonCommercial-ShareAlike 2.0 France", + url: "https://creativecommons.org/licenses/by-nc-sa/2.0/fr/legalcode", + osiApproved: false, }, "D-FSL-1.0": { - "name": "Deutsche Freie Software Lizenz", - "url": "http://www.dipp.nrw.de/d-fsl/lizenzen/", - "osiApproved": false + name: "Deutsche Freie Software Lizenz", + url: "http://www.dipp.nrw.de/d-fsl/lizenzen/", + osiApproved: false, }, - "pnmstitch": { - "name": "pnmstitch License", - "url": "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/editor/pnmstitch.c#l2", - "osiApproved": false + pnmstitch: { + name: "pnmstitch License", + url: "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/editor/pnmstitch.c#l2", + osiApproved: false, }, "CC-BY-SA-2.0-UK": { - "name": "Creative Commons Attribution Share Alike 2.0 England and Wales", - "url": "https://creativecommons.org/licenses/by-sa/2.0/uk/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 2.0 England and Wales", + url: "https://creativecommons.org/licenses/by-sa/2.0/uk/legalcode", + osiApproved: false, }, "CERN-OHL-W-2.0": { - "name": "CERN Open Hardware Licence Version 2 - Weakly Reciprocal", - "url": "https://www.ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2", - "osiApproved": true + name: "CERN Open Hardware Licence Version 2 - Weakly Reciprocal", + url: "https://www.ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2", + osiApproved: true, }, "LPL-1.02": { - "name": "Lucent Public License v1.02", - "url": "http://plan9.bell-labs.com/plan9/license.html", - "osiApproved": true + name: "Lucent Public License v1.02", + url: "http://plan9.bell-labs.com/plan9/license.html", + osiApproved: true, }, "CNRI-Jython": { - "name": "CNRI Jython License", - "url": "http://www.jython.org/license.html", - "osiApproved": false + name: "CNRI Jython License", + url: "http://www.jython.org/license.html", + osiApproved: false, }, "BSD-2-Clause-first-lines": { - "name": "BSD 2-Clause - first lines requirement", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L664-L690", - "osiApproved": false + name: "BSD 2-Clause - first lines requirement", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L664-L690", + osiApproved: false, }, "BSL-1.0": { - "name": "Boost Software License 1.0", - "url": "http://www.boost.org/LICENSE_1_0.txt", - "osiApproved": true + name: "Boost Software License 1.0", + url: "http://www.boost.org/LICENSE_1_0.txt", + osiApproved: true, }, "LZMA-SDK-9.11-to-9.20": { - "name": "LZMA SDK License (versions 9.11 to 9.20)", - "url": "https://www.7-zip.org/sdk.html", - "osiApproved": false + name: "LZMA SDK License (versions 9.11 to 9.20)", + url: "https://www.7-zip.org/sdk.html", + osiApproved: false, }, "Condor-1.1": { - "name": "Condor Public License v1.1", - "url": "http://research.cs.wisc.edu/condor/license.html#condor", - "osiApproved": false + name: "Condor Public License v1.1", + url: "http://research.cs.wisc.edu/condor/license.html#condor", + osiApproved: false, }, "CC-BY-3.0-US": { - "name": "Creative Commons Attribution 3.0 United States", - "url": "https://creativecommons.org/licenses/by/3.0/us/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 United States", + url: "https://creativecommons.org/licenses/by/3.0/us/legalcode", + osiApproved: false, }, "CECILL-C": { - "name": "CeCILL-C Free Software License Agreement", - "url": "http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html", - "osiApproved": false + name: "CeCILL-C Free Software License Agreement", + url: "http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html", + osiApproved: false, }, - "diffmark": { - "name": "diffmark license", - "url": "https://fedoraproject.org/wiki/Licensing/diffmark", - "osiApproved": false + diffmark: { + name: "diffmark license", + url: "https://fedoraproject.org/wiki/Licensing/diffmark", + osiApproved: false, }, "HPND-Kevlin-Henney": { - "name": "Historical Permission Notice and Disclaimer - Kevlin Henney variant", - "url": "https://github.com/mruby/mruby/blob/83d12f8d52522cdb7c8cc46fad34821359f453e6/mrbgems/mruby-dir/src/Win/dirent.c#L127-L140", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - Kevlin Henney variant", + url: "https://github.com/mruby/mruby/blob/83d12f8d52522cdb7c8cc46fad34821359f453e6/mrbgems/mruby-dir/src/Win/dirent.c#L127-L140", + osiApproved: false, }, "GFDL-1.1": { - "name": "GNU Free Documentation License v1.1", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, "StandardML-NJ": { - "name": "Standard ML of New Jersey License", - "url": "https://www.smlnj.org/license.html", - "osiApproved": false + name: "Standard ML of New Jersey License", + url: "https://www.smlnj.org/license.html", + osiApproved: false, }, "RPL-1.1": { - "name": "Reciprocal Public License 1.1", - "url": "https://opensource.org/licenses/RPL-1.1", - "osiApproved": true + name: "Reciprocal Public License 1.1", + url: "https://opensource.org/licenses/RPL-1.1", + osiApproved: true, }, "Hippocratic-2.1": { - "name": "Hippocratic License 2.1", - "url": "https://firstdonoharm.dev/version/2/1/license.html", - "osiApproved": false + name: "Hippocratic License 2.1", + url: "https://firstdonoharm.dev/version/2/1/license.html", + osiApproved: false, }, - "swrule": { - "name": "swrule License", - "url": "https://ctan.math.utah.edu/ctan/tex-archive/macros/generic/misc/swrule.sty", - "osiApproved": false + swrule: { + name: "swrule License", + url: "https://ctan.math.utah.edu/ctan/tex-archive/macros/generic/misc/swrule.sty", + osiApproved: false, }, "CDDL-1.0": { - "name": "Common Development and Distribution License 1.0", - "url": "https://opensource.org/licenses/cddl1", - "osiApproved": true + name: "Common Development and Distribution License 1.0", + url: "https://opensource.org/licenses/cddl1", + osiApproved: true, }, "MS-RL": { - "name": "Microsoft Reciprocal License", - "url": "http://www.microsoft.com/opensource/licenses.mspx", - "osiApproved": true + name: "Microsoft Reciprocal License", + url: "http://www.microsoft.com/opensource/licenses.mspx", + osiApproved: true, }, "any-OSI-perl-modules": { - "name": "Any OSI License - Perl Modules", - "url": "https://metacpan.org/release/JUERD/Exporter-Tidy-0.09/view/Tidy.pm#LICENSE", - "osiApproved": false + name: "Any OSI License - Perl Modules", + url: "https://metacpan.org/release/JUERD/Exporter-Tidy-0.09/view/Tidy.pm#LICENSE", + osiApproved: false, }, "CNRI-Python": { - "name": "CNRI Python License", - "url": "https://opensource.org/licenses/CNRI-Python", - "osiApproved": true + name: "CNRI Python License", + url: "https://opensource.org/licenses/CNRI-Python", + osiApproved: true, }, "OLDAP-2.3": { - "name": "Open LDAP Public License v2.3", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=d32cf54a32d581ab475d23c810b0a7fbaf8d63c3", - "osiApproved": false + name: "Open LDAP Public License v2.3", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=d32cf54a32d581ab475d23c810b0a7fbaf8d63c3", + osiApproved: false, }, "LiLiQ-P-1.1": { - "name": "Licence Libre du Québec – Permissive version 1.1", - "url": "https://forge.gouv.qc.ca/licence/fr/liliq-v1-1/", - "osiApproved": true + name: "Licence Libre du Québec – Permissive version 1.1", + url: "https://forge.gouv.qc.ca/licence/fr/liliq-v1-1/", + osiApproved: true, }, "Python-2.0.1": { - "name": "Python License 2.0.1", - "url": "https://www.python.org/download/releases/2.0.1/license/", - "osiApproved": false + name: "Python License 2.0.1", + url: "https://www.python.org/download/releases/2.0.1/license/", + osiApproved: false, }, - "MakeIndex": { - "name": "MakeIndex License", - "url": "https://fedoraproject.org/wiki/Licensing/MakeIndex", - "osiApproved": false + MakeIndex: { + name: "MakeIndex License", + url: "https://fedoraproject.org/wiki/Licensing/MakeIndex", + osiApproved: false, }, "AFL-1.2": { - "name": "Academic Free License v1.2", - "url": "http://opensource.linux-mirror.org/licenses/afl-1.2.txt", - "osiApproved": true + name: "Academic Free License v1.2", + url: "http://opensource.linux-mirror.org/licenses/afl-1.2.txt", + osiApproved: true, }, "CC-BY-ND-2.0": { - "name": "Creative Commons Attribution No Derivatives 2.0 Generic", - "url": "https://creativecommons.org/licenses/by-nd/2.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution No Derivatives 2.0 Generic", + url: "https://creativecommons.org/licenses/by-nd/2.0/legalcode", + osiApproved: false, }, "FDK-AAC": { - "name": "Fraunhofer FDK AAC Codec Library", - "url": "https://fedoraproject.org/wiki/Licensing/FDK-AAC", - "osiApproved": false + name: "Fraunhofer FDK AAC Codec Library", + url: "https://fedoraproject.org/wiki/Licensing/FDK-AAC", + osiApproved: false, }, - "SL": { - "name": "SL License", - "url": "https://github.com/mtoyoda/sl/blob/master/LICENSE", - "osiApproved": false + SL: { + name: "SL License", + url: "https://github.com/mtoyoda/sl/blob/master/LICENSE", + osiApproved: false, }, "TU-Berlin-1.0": { - "name": "Technische Universitaet Berlin License 1.0", - "url": "https://github.com/swh/ladspa/blob/7bf6f3799fdba70fda297c2d8fd9f526803d9680/gsm/COPYRIGHT", - "osiApproved": false + name: "Technische Universitaet Berlin License 1.0", + url: "https://github.com/swh/ladspa/blob/7bf6f3799fdba70fda297c2d8fd9f526803d9680/gsm/COPYRIGHT", + osiApproved: false, }, "GPL-1.0+": { - "name": "GNU General Public License v1.0 or later", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", - "osiApproved": false + name: "GNU General Public License v1.0 or later", + url: "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", + osiApproved: false, }, - "Saxpath": { - "name": "Saxpath License", - "url": "https://fedoraproject.org/wiki/Licensing/Saxpath_License", - "osiApproved": false + Saxpath: { + name: "Saxpath License", + url: "https://fedoraproject.org/wiki/Licensing/Saxpath_License", + osiApproved: false, }, - "dvipdfm": { - "name": "dvipdfm License", - "url": "https://fedoraproject.org/wiki/Licensing/dvipdfm", - "osiApproved": false + dvipdfm: { + name: "dvipdfm License", + url: "https://fedoraproject.org/wiki/Licensing/dvipdfm", + osiApproved: false, }, "BSD-2-Clause-Darwin": { - "name": "BSD 2-Clause - Ian Darwin variant", - "url": "https://github.com/file/file/blob/master/COPYING", - "osiApproved": false + name: "BSD 2-Clause - Ian Darwin variant", + url: "https://github.com/file/file/blob/master/COPYING", + osiApproved: false, }, "CPAL-1.0": { - "name": "Common Public Attribution License 1.0", - "url": "https://opensource.org/licenses/CPAL-1.0", - "osiApproved": true + name: "Common Public Attribution License 1.0", + url: "https://opensource.org/licenses/CPAL-1.0", + osiApproved: true, }, "copyleft-next-0.3.1": { - "name": "copyleft-next 0.3.1", - "url": "https://github.com/copyleft-next/copyleft-next/blob/master/Releases/copyleft-next-0.3.1", - "osiApproved": false + name: "copyleft-next 0.3.1", + url: "https://github.com/copyleft-next/copyleft-next/blob/master/Releases/copyleft-next-0.3.1", + osiApproved: false, }, - "NetCDF": { - "name": "NetCDF license", - "url": "http://www.unidata.ucar.edu/software/netcdf/copyright.html", - "osiApproved": false + NetCDF: { + name: "NetCDF license", + url: "http://www.unidata.ucar.edu/software/netcdf/copyright.html", + osiApproved: false, }, - "FTL": { - "name": "Freetype Project License", - "url": "http://freetype.fis.uniroma2.it/FTL.TXT", - "osiApproved": false + FTL: { + name: "Freetype Project License", + url: "http://freetype.fis.uniroma2.it/FTL.TXT", + osiApproved: false, }, "DocBook-Schema": { - "name": "DocBook Schema License", - "url": "https://github.com/docbook/xslt10-stylesheets/blob/efd62655c11cc8773708df7a843613fa1e932bf8/xsl/assembly/schema/docbook51b7.rnc", - "osiApproved": false + name: "DocBook Schema License", + url: "https://github.com/docbook/xslt10-stylesheets/blob/efd62655c11cc8773708df7a843613fa1e932bf8/xsl/assembly/schema/docbook51b7.rnc", + osiApproved: false, }, "CERN-OHL-S-2.0": { - "name": "CERN Open Hardware Licence Version 2 - Strongly Reciprocal", - "url": "https://www.ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2", - "osiApproved": true + name: "CERN Open Hardware Licence Version 2 - Strongly Reciprocal", + url: "https://www.ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2", + osiApproved: true, }, "X11-distribute-modifications-variant": { - "name": "X11 License Distribution Modification Variant", - "url": "https://github.com/mirror/ncurses/blob/master/COPYING", - "osiApproved": false + name: "X11 License Distribution Modification Variant", + url: "https://github.com/mirror/ncurses/blob/master/COPYING", + osiApproved: false, }, "copyleft-next-0.3.0": { - "name": "copyleft-next 0.3.0", - "url": "https://github.com/copyleft-next/copyleft-next/blob/master/Releases/copyleft-next-0.3.0", - "osiApproved": false + name: "copyleft-next 0.3.0", + url: "https://github.com/copyleft-next/copyleft-next/blob/master/Releases/copyleft-next-0.3.0", + osiApproved: false, }, - "X11": { - "name": "X11 License", - "url": "http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3", - "osiApproved": false + X11: { + name: "X11 License", + url: "http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3", + osiApproved: false, }, "CC-BY-NC-SA-2.0-DE": { - "name": "Creative Commons Attribution Non Commercial Share Alike 2.0 Germany", - "url": "https://creativecommons.org/licenses/by-nc-sa/2.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 2.0 Germany", + url: "https://creativecommons.org/licenses/by-nc-sa/2.0/de/legalcode", + osiApproved: false, }, "GFDL-1.3-only": { - "name": "GNU Free Documentation License v1.3 only", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3 only", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, - "Bahyph": { - "name": "Bahyph License", - "url": "https://fedoraproject.org/wiki/Licensing/Bahyph", - "osiApproved": false + Bahyph: { + name: "Bahyph License", + url: "https://fedoraproject.org/wiki/Licensing/Bahyph", + osiApproved: false, }, "LGPL-3.0-or-later": { - "name": "GNU Lesser General Public License v3.0 or later", - "url": "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v3.0 or later", + url: "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", + osiApproved: true, }, "ZPL-1.1": { - "name": "Zope Public License 1.1", - "url": "http://old.zope.org/Resources/License/ZPL-1.1", - "osiApproved": false + name: "Zope Public License 1.1", + url: "http://old.zope.org/Resources/License/ZPL-1.1", + osiApproved: false, }, "gSOAP-1.3b": { - "name": "gSOAP Public License v1.3b", - "url": "http://www.cs.fsu.edu/~engelen/license.html", - "osiApproved": false + name: "gSOAP Public License v1.3b", + url: "http://www.cs.fsu.edu/~engelen/license.html", + osiApproved: false, }, "JasPer-2.0": { - "name": "JasPer License", - "url": "http://www.ece.uvic.ca/~mdadams/jasper/LICENSE", - "osiApproved": false + name: "JasPer License", + url: "http://www.ece.uvic.ca/~mdadams/jasper/LICENSE", + osiApproved: false, }, "Sendmail-Open-Source-1.1": { - "name": "Sendmail Open Source License v1.1", - "url": "https://github.com/trusteddomainproject/OpenDMARC/blob/master/LICENSE.Sendmail", - "osiApproved": false + name: "Sendmail Open Source License v1.1", + url: "https://github.com/trusteddomainproject/OpenDMARC/blob/master/LICENSE.Sendmail", + osiApproved: false, }, "BUSL-1.1": { - "name": "Business Source License 1.1", - "url": "https://mariadb.com/bsl11/", - "osiApproved": false + name: "Business Source License 1.1", + url: "https://mariadb.com/bsl11/", + osiApproved: false, }, - "Eurosym": { - "name": "Eurosym License", - "url": "https://fedoraproject.org/wiki/Licensing/Eurosym", - "osiApproved": false + Eurosym: { + name: "Eurosym License", + url: "https://fedoraproject.org/wiki/Licensing/Eurosym", + osiApproved: false, }, - "ThirdEye": { - "name": "ThirdEye License", - "url": "https://sourceware.org/cgit/binutils-gdb/tree/include/coff/symconst.h#n11", - "osiApproved": false + ThirdEye: { + name: "ThirdEye License", + url: "https://sourceware.org/cgit/binutils-gdb/tree/include/coff/symconst.h#n11", + osiApproved: false, }, "CC-SA-1.0": { - "name": "Creative Commons Share Alike 1.0 Generic", - "url": "https://creativecommons.org/licenses/sa/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Share Alike 1.0 Generic", + url: "https://creativecommons.org/licenses/sa/1.0/legalcode", + osiApproved: false, }, "Watcom-1.0": { - "name": "Sybase Open Watcom Public License 1.0", - "url": "https://opensource.org/licenses/Watcom-1.0", - "osiApproved": true + name: "Sybase Open Watcom Public License 1.0", + url: "https://opensource.org/licenses/Watcom-1.0", + osiApproved: true, }, - "Caldera": { - "name": "Caldera License", - "url": "http://www.lemis.com/grog/UNIX/ancient-source-all.pdf", - "osiApproved": false + Caldera: { + name: "Caldera License", + url: "http://www.lemis.com/grog/UNIX/ancient-source-all.pdf", + osiApproved: false, }, "Parity-7.0.0": { - "name": "The Parity Public License 7.0.0", - "url": "https://paritylicense.com/versions/7.0.0.html", - "osiApproved": false + name: "The Parity Public License 7.0.0", + url: "https://paritylicense.com/versions/7.0.0.html", + osiApproved: false, }, - "SMPPL": { - "name": "Secure Messaging Protocol Public License", - "url": "https://github.com/dcblake/SMP/blob/master/Documentation/License.txt", - "osiApproved": false + SMPPL: { + name: "Secure Messaging Protocol Public License", + url: "https://github.com/dcblake/SMP/blob/master/Documentation/License.txt", + osiApproved: false, }, "AGPL-1.0": { - "name": "Affero General Public License v1.0", - "url": "http://www.affero.org/oagpl.html", - "osiApproved": false + name: "Affero General Public License v1.0", + url: "http://www.affero.org/oagpl.html", + osiApproved: false, }, "MulanPSL-2.0": { - "name": "Mulan Permissive Software License, Version 2", - "url": "https://license.coscl.org.cn/MulanPSL2", - "osiApproved": true + name: "Mulan Permissive Software License, Version 2", + url: "https://license.coscl.org.cn/MulanPSL2", + osiApproved: true, }, - "Afmparse": { - "name": "Afmparse License", - "url": "https://fedoraproject.org/wiki/Licensing/Afmparse", - "osiApproved": false + Afmparse: { + name: "Afmparse License", + url: "https://fedoraproject.org/wiki/Licensing/Afmparse", + osiApproved: false, }, "GFDL-1.2-no-invariants-or-later": { - "name": "GNU Free Documentation License v1.2 or later - no invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2 or later - no invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, "Lucida-Bitmap-Fonts": { - "name": "Lucida Bitmap Fonts License", - "url": "https://gitlab.freedesktop.org/xorg/font/bh-100dpi/-/blob/master/COPYING?ref_type=heads", - "osiApproved": false + name: "Lucida Bitmap Fonts License", + url: "https://gitlab.freedesktop.org/xorg/font/bh-100dpi/-/blob/master/COPYING?ref_type=heads", + osiApproved: false, }, "DRL-1.0": { - "name": "Detection Rule License 1.0", - "url": "https://github.com/Neo23x0/sigma/blob/master/LICENSE.Detection.Rules.md", - "osiApproved": false + name: "Detection Rule License 1.0", + url: "https://github.com/Neo23x0/sigma/blob/master/LICENSE.Detection.Rules.md", + osiApproved: false, }, "CC-BY-NC-2.5": { - "name": "Creative Commons Attribution Non Commercial 2.5 Generic", - "url": "https://creativecommons.org/licenses/by-nc/2.5/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial 2.5 Generic", + url: "https://creativecommons.org/licenses/by-nc/2.5/legalcode", + osiApproved: false, }, - "GD": { - "name": "GD License", - "url": "https://libgd.github.io/manuals/2.3.0/files/license-txt.html", - "osiApproved": false + GD: { + name: "GD License", + url: "https://libgd.github.io/manuals/2.3.0/files/license-txt.html", + osiApproved: false, }, "Zend-2.0": { - "name": "Zend License v2.0", - "url": "https://web.archive.org/web/20130517195954/http://www.zend.com/license/2_00.txt", - "osiApproved": false + name: "Zend License v2.0", + url: "https://web.archive.org/web/20130517195954/http://www.zend.com/license/2_00.txt", + osiApproved: false, }, - "Cronyx": { - "name": "Cronyx License", - "url": "https://gitlab.freedesktop.org/xorg/font/alias/-/blob/master/COPYING", - "osiApproved": false + Cronyx: { + name: "Cronyx License", + url: "https://gitlab.freedesktop.org/xorg/font/alias/-/blob/master/COPYING", + osiApproved: false, }, - "TTYP0": { - "name": "TTYP0 License", - "url": "https://people.mpi-inf.mpg.de/~uwe/misc/uw-ttyp0/", - "osiApproved": false + TTYP0: { + name: "TTYP0 License", + url: "https://people.mpi-inf.mpg.de/~uwe/misc/uw-ttyp0/", + osiApproved: false, }, "CC-BY-ND-1.0": { - "name": "Creative Commons Attribution No Derivatives 1.0 Generic", - "url": "https://creativecommons.org/licenses/by-nd/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution No Derivatives 1.0 Generic", + url: "https://creativecommons.org/licenses/by-nd/1.0/legalcode", + osiApproved: false, }, "Ferguson-Twofish": { - "name": "Ferguson Twofish License", - "url": "https://github.com/wernerd/ZRTPCPP/blob/6b3cd8e6783642292bad0c21e3e5e5ce45ff3e03/cryptcommon/twofish.c#L113C3-L127", - "osiApproved": false + name: "Ferguson Twofish License", + url: "https://github.com/wernerd/ZRTPCPP/blob/6b3cd8e6783642292bad0c21e3e5e5ce45ff3e03/cryptcommon/twofish.c#L113C3-L127", + osiApproved: false, }, - "SchemeReport": { - "name": "Scheme Language Report License", - "osiApproved": false + SchemeReport: { + name: "Scheme Language Report License", + osiApproved: false, }, "MIT-Khronos-old": { - "name": "MIT Khronos - old variant", - "url": "https://github.com/KhronosGroup/SPIRV-Cross/blob/main/LICENSES/LicenseRef-KhronosFreeUse.txt", - "osiApproved": false + name: "MIT Khronos - old variant", + url: "https://github.com/KhronosGroup/SPIRV-Cross/blob/main/LICENSES/LicenseRef-KhronosFreeUse.txt", + osiApproved: false, }, "LPD-document": { - "name": "LPD Documentation License", - "url": "https://github.com/Cyan4973/xxHash/blob/dev/doc/xxhash_spec.md", - "osiApproved": false + name: "LPD Documentation License", + url: "https://github.com/Cyan4973/xxHash/blob/dev/doc/xxhash_spec.md", + osiApproved: false, }, "UPL-1.0": { - "name": "Universal Permissive License v1.0", - "url": "https://opensource.org/licenses/UPL", - "osiApproved": true + name: "Universal Permissive License v1.0", + url: "https://opensource.org/licenses/UPL", + osiApproved: true, }, "CECILL-1.1": { - "name": "CeCILL Free Software License Agreement v1.1", - "url": "http://www.cecill.info/licences/Licence_CeCILL_V1.1-US.html", - "osiApproved": false + name: "CeCILL Free Software License Agreement v1.1", + url: "http://www.cecill.info/licences/Licence_CeCILL_V1.1-US.html", + osiApproved: false, }, - "Crossword": { - "name": "Crossword License", - "url": "https://fedoraproject.org/wiki/Licensing/Crossword", - "osiApproved": false + Crossword: { + name: "Crossword License", + url: "https://fedoraproject.org/wiki/Licensing/Crossword", + osiApproved: false, }, "C-UDA-1.0": { - "name": "Computational Use of Data Agreement v1.0", - "url": "https://github.com/microsoft/Computational-Use-of-Data-Agreement/blob/master/C-UDA-1.0.md", - "osiApproved": false + name: "Computational Use of Data Agreement v1.0", + url: "https://github.com/microsoft/Computational-Use-of-Data-Agreement/blob/master/C-UDA-1.0.md", + osiApproved: false, }, "BSD-3-Clause-HP": { - "name": "Hewlett-Packard BSD variant license", - "url": "https://github.com/zdohnal/hplip/blob/master/COPYING#L939", - "osiApproved": false + name: "Hewlett-Packard BSD variant license", + url: "https://github.com/zdohnal/hplip/blob/master/COPYING#L939", + osiApproved: false, }, "Apache-1.0": { - "name": "Apache License 1.0", - "url": "http://www.apache.org/licenses/LICENSE-1.0", - "osiApproved": false + name: "Apache License 1.0", + url: "http://www.apache.org/licenses/LICENSE-1.0", + osiApproved: false, }, "CERN-OHL-1.1": { - "name": "CERN Open Hardware Licence v1.1", - "url": "https://www.ohwr.org/project/licenses/wikis/cern-ohl-v1.1", - "osiApproved": false + name: "CERN Open Hardware Licence v1.1", + url: "https://www.ohwr.org/project/licenses/wikis/cern-ohl-v1.1", + osiApproved: false, }, - "SISSL": { - "name": "Sun Industry Standards Source License v1.1", - "url": "http://www.openoffice.org/licenses/sissl_license.html", - "osiApproved": true + SISSL: { + name: "Sun Industry Standards Source License v1.1", + url: "http://www.openoffice.org/licenses/sissl_license.html", + osiApproved: true, }, "MPL-2.0-no-copyleft-exception": { - "name": "Mozilla Public License 2.0 (no copyleft exception)", - "url": "https://www.mozilla.org/MPL/2.0/", - "osiApproved": true + name: "Mozilla Public License 2.0 (no copyleft exception)", + url: "https://www.mozilla.org/MPL/2.0/", + osiApproved: true, }, "OLFL-1.3": { - "name": "Open Logistics Foundation License Version 1.3", - "url": "https://openlogisticsfoundation.org/licenses/", - "osiApproved": true + name: "Open Logistics Foundation License Version 1.3", + url: "https://openlogisticsfoundation.org/licenses/", + osiApproved: true, }, "Inner-Net-2.0": { - "name": "Inner Net License v2.0", - "url": "https://fedoraproject.org/wiki/Licensing/Inner_Net_License", - "osiApproved": false + name: "Inner Net License v2.0", + url: "https://fedoraproject.org/wiki/Licensing/Inner_Net_License", + osiApproved: false, }, "GPL-1.0-only": { - "name": "GNU General Public License v1.0 only", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", - "osiApproved": false + name: "GNU General Public License v1.0 only", + url: "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", + osiApproved: false, }, "LiLiQ-R-1.1": { - "name": "Licence Libre du Québec – Réciprocité version 1.1", - "url": "https://www.forge.gouv.qc.ca/participez/licence-logicielle/licence-libre-du-quebec-liliq-en-francais/licence-libre-du-quebec-reciprocite-liliq-r-v1-1/", - "osiApproved": true + name: "Licence Libre du Québec – Réciprocité version 1.1", + url: "https://www.forge.gouv.qc.ca/participez/licence-logicielle/licence-libre-du-quebec-liliq-en-francais/licence-libre-du-quebec-reciprocite-liliq-r-v1-1/", + osiApproved: true, }, "BSD-4.3TAHOE": { - "name": "BSD 4.3 TAHOE License", - "url": "https://github.com/389ds/389-ds-base/blob/main/ldap/include/sysexits-compat.h#L15", - "osiApproved": false + name: "BSD 4.3 TAHOE License", + url: "https://github.com/389ds/389-ds-base/blob/main/ldap/include/sysexits-compat.h#L15", + osiApproved: false, }, "AFL-2.0": { - "name": "Academic Free License v2.0", - "url": "http://wayback.archive.org/web/20060924134533/http://www.opensource.org/licenses/afl-2.0.txt", - "osiApproved": true + name: "Academic Free License v2.0", + url: "http://wayback.archive.org/web/20060924134533/http://www.opensource.org/licenses/afl-2.0.txt", + osiApproved: true, }, "GFDL-1.2-invariants-or-later": { - "name": "GNU Free Documentation License v1.2 or later - invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2 or later - invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, "CC-BY-NC-ND-2.5": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 2.5 Generic", - "url": "https://creativecommons.org/licenses/by-nc-nd/2.5/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 2.5 Generic", + url: "https://creativecommons.org/licenses/by-nc-nd/2.5/legalcode", + osiApproved: false, }, "OLDAP-2.4": { - "name": "Open LDAP Public License v2.4", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=cd1284c4a91a8a380d904eee68d1583f989ed386", - "osiApproved": false + name: "Open LDAP Public License v2.4", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=cd1284c4a91a8a380d904eee68d1583f989ed386", + osiApproved: false, }, "Brian-Gladman-3-Clause": { - "name": "Brian Gladman 3-Clause License", - "url": "https://github.com/SWI-Prolog/packages-clib/blob/master/sha1/brg_endian.h", - "osiApproved": false + name: "Brian Gladman 3-Clause License", + url: "https://github.com/SWI-Prolog/packages-clib/blob/master/sha1/brg_endian.h", + osiApproved: false, }, - "gtkbook": { - "name": "gtkbook License", - "url": "https://github.com/slogan621/gtkbook", - "osiApproved": false + gtkbook: { + name: "gtkbook License", + url: "https://github.com/slogan621/gtkbook", + osiApproved: false, }, "OFL-1.0-no-RFN": { - "name": "SIL Open Font License 1.0 with no Reserved Font Name", - "url": "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL10_web", - "osiApproved": false + name: "SIL Open Font License 1.0 with no Reserved Font Name", + url: "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL10_web", + osiApproved: false, }, "LAL-1.3": { - "name": "Licence Art Libre 1.3", - "url": "https://artlibre.org/", - "osiApproved": false + name: "Licence Art Libre 1.3", + url: "https://artlibre.org/", + osiApproved: false, }, - "threeparttable": { - "name": "threeparttable License", - "url": "https://fedoraproject.org/wiki/Licensing/Threeparttable", - "osiApproved": false + threeparttable: { + name: "threeparttable License", + url: "https://fedoraproject.org/wiki/Licensing/Threeparttable", + osiApproved: false, }, - "Imlib2": { - "name": "Imlib2 License", - "url": "http://trac.enlightenment.org/e/browser/trunk/imlib2/COPYING", - "osiApproved": false + Imlib2: { + name: "Imlib2 License", + url: "http://trac.enlightenment.org/e/browser/trunk/imlib2/COPYING", + osiApproved: false, }, "Adobe-Display-PostScript": { - "name": "Adobe Display PostScript License", - "url": "https://gitlab.freedesktop.org/xorg/xserver/-/blob/master/COPYING?ref_type=heads#L752", - "osiApproved": false + name: "Adobe Display PostScript License", + url: "https://gitlab.freedesktop.org/xorg/xserver/-/blob/master/COPYING?ref_type=heads#L752", + osiApproved: false, }, - "Xnet": { - "name": "X.Net License", - "url": "https://opensource.org/licenses/Xnet", - "osiApproved": true + Xnet: { + name: "X.Net License", + url: "https://opensource.org/licenses/Xnet", + osiApproved: true, }, "OSL-2.1": { - "name": "Open Software License 2.1", - "url": "http://web.archive.org/web/20050212003940/http://www.rosenlaw.com/osl21.htm", - "osiApproved": true + name: "Open Software License 2.1", + url: "http://web.archive.org/web/20050212003940/http://www.rosenlaw.com/osl21.htm", + osiApproved: true, }, "OLDAP-2.2": { - "name": "Open LDAP Public License v2.2", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=470b0c18ec67621c85881b2733057fecf4a1acc3", - "osiApproved": false + name: "Open LDAP Public License v2.2", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=470b0c18ec67621c85881b2733057fecf4a1acc3", + osiApproved: false, }, "MS-LPL": { - "name": "Microsoft Limited Public License", - "url": "https://www.openhub.net/licenses/mslpl", - "osiApproved": false + name: "Microsoft Limited Public License", + url: "https://www.openhub.net/licenses/mslpl", + osiApproved: false, }, - "Mup": { - "name": "Mup License", - "url": "https://fedoraproject.org/wiki/Licensing/Mup", - "osiApproved": false + Mup: { + name: "Mup License", + url: "https://fedoraproject.org/wiki/Licensing/Mup", + osiApproved: false, }, "LGPL-3.0": { - "name": "GNU Lesser General Public License v3.0 only", - "url": "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v3.0 only", + url: "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", + osiApproved: true, }, "BSD-4.3RENO": { - "name": "BSD 4.3 RENO License", - "url": "https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=libiberty/strcasecmp.c;h=131d81c2ce7881fa48c363dc5bf5fb302c61ce0b;hb=HEAD", - "osiApproved": false + name: "BSD 4.3 RENO License", + url: "https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=libiberty/strcasecmp.c;h=131d81c2ce7881fa48c363dc5bf5fb302c61ce0b;hb=HEAD", + osiApproved: false, }, "MIT-Click": { - "name": "MIT Click License", - "url": "https://github.com/kohler/t1utils/blob/master/LICENSE", - "osiApproved": false + name: "MIT Click License", + url: "https://github.com/kohler/t1utils/blob/master/LICENSE", + osiApproved: false, }, "W3C-20150513": { - "name": "W3C Software Notice and Document License (2015-05-13)", - "url": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document", - "osiApproved": true + name: "W3C Software Notice and Document License (2015-05-13)", + url: "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document", + osiApproved: true, }, "GPL-1.0-or-later": { - "name": "GNU General Public License v1.0 or later", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", - "osiApproved": false + name: "GNU General Public License v1.0 or later", + url: "https://www.gnu.org/licenses/old-licenses/gpl-1.0-standalone.html", + osiApproved: false, }, "OSL-2.0": { - "name": "Open Software License 2.0", - "url": "http://web.archive.org/web/20041020171434/http://www.rosenlaw.com/osl2.0.html", - "osiApproved": true + name: "Open Software License 2.0", + url: "http://web.archive.org/web/20041020171434/http://www.rosenlaw.com/osl2.0.html", + osiApproved: true, }, "EPL-2.0": { - "name": "Eclipse Public License 2.0", - "url": "https://www.eclipse.org/legal/epl-2.0", - "osiApproved": true + name: "Eclipse Public License 2.0", + url: "https://www.eclipse.org/legal/epl-2.0", + osiApproved: true, }, "GFDL-1.3": { - "name": "GNU Free Documentation License v1.3", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, "ASWF-Digital-Assets-1.0": { - "name": "ASWF Digital Assets License version 1.0", - "url": "https://github.com/AcademySoftwareFoundation/foundation/blob/main/digital_assets/aswf_digital_assets_license_v1.0.txt", - "osiApproved": false + name: "ASWF Digital Assets License version 1.0", + url: "https://github.com/AcademySoftwareFoundation/foundation/blob/main/digital_assets/aswf_digital_assets_license_v1.0.txt", + osiApproved: false, }, "APSL-1.1": { - "name": "Apple Public Source License 1.1", - "url": "http://www.opensource.apple.com/source/IOSerialFamily/IOSerialFamily-7/APPLE_LICENSE", - "osiApproved": true + name: "Apple Public Source License 1.1", + url: "http://www.opensource.apple.com/source/IOSerialFamily/IOSerialFamily-7/APPLE_LICENSE", + osiApproved: true, }, - "HPND": { - "name": "Historical Permission Notice and Disclaimer", - "url": "https://opensource.org/licenses/HPND", - "osiApproved": true + HPND: { + name: "Historical Permission Notice and Disclaimer", + url: "https://opensource.org/licenses/HPND", + osiApproved: true, }, "Linux-OpenIB": { - "name": "Linux Kernel Variant of OpenIB.org license", - "url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/infiniband/core/sa.h", - "osiApproved": false + name: "Linux Kernel Variant of OpenIB.org license", + url: "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/infiniband/core/sa.h", + osiApproved: false, }, - "Zeeff": { - "name": "Zeeff License", - "url": "ftp://ftp.tin.org/pub/news/utils/newsx/newsx-1.6.tar.gz", - "osiApproved": false + Zeeff: { + name: "Zeeff License", + url: "ftp://ftp.tin.org/pub/news/utils/newsx/newsx-1.6.tar.gz", + osiApproved: false, }, "OGL-UK-3.0": { - "name": "Open Government Licence v3.0", - "url": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/", - "osiApproved": false + name: "Open Government Licence v3.0", + url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/", + osiApproved: false, }, "CC-BY-ND-3.0-DE": { - "name": "Creative Commons Attribution No Derivatives 3.0 Germany", - "url": "https://creativecommons.org/licenses/by-nd/3.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution No Derivatives 3.0 Germany", + url: "https://creativecommons.org/licenses/by-nd/3.0/de/legalcode", + osiApproved: false, }, "BSD-4-Clause-Shortened": { - "name": "BSD 4 Clause Shortened", - "url": "https://metadata.ftp-master.debian.org/changelogs//main/a/arpwatch/arpwatch_2.1a15-7_copyright", - "osiApproved": false + name: "BSD 4 Clause Shortened", + url: "https://metadata.ftp-master.debian.org/changelogs//main/a/arpwatch/arpwatch_2.1a15-7_copyright", + osiApproved: false, }, "BSD-2-Clause-FreeBSD": { - "name": "BSD 2-Clause FreeBSD License", - "url": "http://www.freebsd.org/copyright/freebsd-license.html", - "osiApproved": false + name: "BSD 2-Clause FreeBSD License", + url: "http://www.freebsd.org/copyright/freebsd-license.html", + osiApproved: false, }, - "gnuplot": { - "name": "gnuplot License", - "url": "https://fedoraproject.org/wiki/Licensing/Gnuplot", - "osiApproved": false + gnuplot: { + name: "gnuplot License", + url: "https://fedoraproject.org/wiki/Licensing/Gnuplot", + osiApproved: false, }, "libpng-2.0": { - "name": "PNG Reference Library version 2", - "url": "http://www.libpng.org/pub/png/src/libpng-LICENSE.txt", - "osiApproved": false + name: "PNG Reference Library version 2", + url: "http://www.libpng.org/pub/png/src/libpng-LICENSE.txt", + osiApproved: false, }, - "Leptonica": { - "name": "Leptonica License", - "url": "https://fedoraproject.org/wiki/Licensing/Leptonica", - "osiApproved": false + Leptonica: { + name: "Leptonica License", + url: "https://fedoraproject.org/wiki/Licensing/Leptonica", + osiApproved: false, }, - "Clips": { - "name": "Clips License", - "url": "https://github.com/DrItanium/maya/blob/master/LICENSE.CLIPS", - "osiApproved": false + Clips: { + name: "Clips License", + url: "https://github.com/DrItanium/maya/blob/master/LICENSE.CLIPS", + osiApproved: false, }, - "OpenSSL": { - "name": "OpenSSL License", - "url": "http://www.openssl.org/source/license.html", - "osiApproved": false + OpenSSL: { + name: "OpenSSL License", + url: "http://www.openssl.org/source/license.html", + osiApproved: false, }, - "Sendmail": { - "name": "Sendmail License", - "url": "http://www.sendmail.com/pdfs/open_source/sendmail_license.pdf", - "osiApproved": false + Sendmail: { + name: "Sendmail License", + url: "http://www.sendmail.com/pdfs/open_source/sendmail_license.pdf", + osiApproved: false, }, "NCBI-PD": { - "name": "NCBI Public Domain Notice", - "url": "https://github.com/ncbi/sra-tools/blob/e8e5b6af4edc460156ad9ce5902d0779cffbf685/LICENSE", - "osiApproved": false + name: "NCBI Public Domain Notice", + url: "https://github.com/ncbi/sra-tools/blob/e8e5b6af4edc460156ad9ce5902d0779cffbf685/LICENSE", + osiApproved: false, }, - "TrustedQSL": { - "name": "TrustedQSL License", - "url": "https://sourceforge.net/p/trustedqsl/tqsl/ci/master/tree/LICENSE.txt", - "osiApproved": false + TrustedQSL: { + name: "TrustedQSL License", + url: "https://sourceforge.net/p/trustedqsl/tqsl/ci/master/tree/LICENSE.txt", + osiApproved: false, }, - "Catharon": { - "name": "Catharon License", - "url": "https://github.com/scummvm/scummvm/blob/v2.8.0/LICENSES/CatharonLicense.txt", - "osiApproved": false + Catharon: { + name: "Catharon License", + url: "https://github.com/scummvm/scummvm/blob/v2.8.0/LICENSES/CatharonLicense.txt", + osiApproved: false, }, "EUPL-1.2": { - "name": "European Union Public License 1.2", - "url": "https://joinup.ec.europa.eu/page/eupl-text-11-12", - "osiApproved": true + name: "European Union Public License 1.2", + url: "https://joinup.ec.europa.eu/page/eupl-text-11-12", + osiApproved: true, }, - "Wsuipa": { - "name": "Wsuipa License", - "url": "https://fedoraproject.org/wiki/Licensing/Wsuipa", - "osiApproved": false + Wsuipa: { + name: "Wsuipa License", + url: "https://fedoraproject.org/wiki/Licensing/Wsuipa", + osiApproved: false, }, "OGL-UK-2.0": { - "name": "Open Government Licence v2.0", - "url": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/2/", - "osiApproved": false + name: "Open Government Licence v2.0", + url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/2/", + osiApproved: false, }, "ISC-Veillard": { - "name": "ISC Veillard variant", - "url": "https://raw.githubusercontent.com/GNOME/libxml2/4c2e7c651f6c2f0d1a74f350cbda95f7df3e7017/hash.c", - "osiApproved": false + name: "ISC Veillard variant", + url: "https://raw.githubusercontent.com/GNOME/libxml2/4c2e7c651f6c2f0d1a74f350cbda95f7df3e7017/hash.c", + osiApproved: false, }, "CC-BY-3.0-NL": { - "name": "Creative Commons Attribution 3.0 Netherlands", - "url": "https://creativecommons.org/licenses/by/3.0/nl/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 3.0 Netherlands", + url: "https://creativecommons.org/licenses/by/3.0/nl/legalcode", + osiApproved: false, }, "AdaCore-doc": { - "name": "AdaCore Doc License", - "url": "https://github.com/AdaCore/xmlada/blob/master/docs/index.rst", - "osiApproved": false + name: "AdaCore Doc License", + url: "https://github.com/AdaCore/xmlada/blob/master/docs/index.rst", + osiApproved: false, }, "AGPL-1.0-only": { - "name": "Affero General Public License v1.0 only", - "url": "http://www.affero.org/oagpl.html", - "osiApproved": false + name: "Affero General Public License v1.0 only", + url: "http://www.affero.org/oagpl.html", + osiApproved: false, }, "LGPL-3.0+": { - "name": "GNU Lesser General Public License v3.0 or later", - "url": "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v3.0 or later", + url: "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", + osiApproved: true, }, "libselinux-1.0": { - "name": "libselinux public domain notice", - "url": "https://github.com/SELinuxProject/selinux/blob/master/libselinux/LICENSE", - "osiApproved": false + name: "libselinux public domain notice", + url: "https://github.com/SELinuxProject/selinux/blob/master/libselinux/LICENSE", + osiApproved: false, }, "HPND-Fenneberg-Livingston": { - "name": "Historical Permission Notice and Disclaimer - Fenneberg-Livingston variant", - "url": "https://github.com/FreeRADIUS/freeradius-client/blob/master/COPYRIGHT#L32", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - Fenneberg-Livingston variant", + url: "https://github.com/FreeRADIUS/freeradius-client/blob/master/COPYRIGHT#L32", + osiApproved: false, }, "Xdebug-1.03": { - "name": "Xdebug License v 1.03", - "url": "https://github.com/xdebug/xdebug/blob/master/LICENSE", - "osiApproved": false + name: "Xdebug License v 1.03", + url: "https://github.com/xdebug/xdebug/blob/master/LICENSE", + osiApproved: false, }, - "Jam": { - "name": "Jam License", - "url": "https://www.boost.org/doc/libs/1_35_0/doc/html/jam.html", - "osiApproved": true + Jam: { + name: "Jam License", + url: "https://www.boost.org/doc/libs/1_35_0/doc/html/jam.html", + osiApproved: true, }, "GPL-2.0-with-classpath-exception": { - "name": "GNU General Public License v2.0 w/Classpath exception", - "url": "https://www.gnu.org/software/classpath/license.html", - "osiApproved": false + name: "GNU General Public License v2.0 w/Classpath exception", + url: "https://www.gnu.org/software/classpath/license.html", + osiApproved: false, }, "check-cvs": { - "name": "check-cvs License", - "url": "http://cvs.savannah.gnu.org/viewvc/cvs/ccvs/contrib/check_cvs.in?revision=1.1.4.3&view=markup&pathrev=cvs1-11-23#l2", - "osiApproved": false + name: "check-cvs License", + url: "http://cvs.savannah.gnu.org/viewvc/cvs/ccvs/contrib/check_cvs.in?revision=1.1.4.3&view=markup&pathrev=cvs1-11-23#l2", + osiApproved: false, }, "LGPL-2.0+": { - "name": "GNU Library General Public License v2 or later", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", - "osiApproved": true + name: "GNU Library General Public License v2 or later", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", + osiApproved: true, }, "AMD-newlib": { - "name": "AMD newlib License", - "url": "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/sys/a29khif/_close.S;h=04f52ae00de1dafbd9055ad8d73c5c697a3aae7f;hb=HEAD", - "osiApproved": false + name: "AMD newlib License", + url: "https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/sys/a29khif/_close.S;h=04f52ae00de1dafbd9055ad8d73c5c697a3aae7f;hb=HEAD", + osiApproved: false, }, "CC-BY-NC-1.0": { - "name": "Creative Commons Attribution Non Commercial 1.0 Generic", - "url": "https://creativecommons.org/licenses/by-nc/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial 1.0 Generic", + url: "https://creativecommons.org/licenses/by-nc/1.0/legalcode", + osiApproved: false, }, - "xinetd": { - "name": "xinetd License", - "url": "https://fedoraproject.org/wiki/Licensing/Xinetd_License", - "osiApproved": false + xinetd: { + name: "xinetd License", + url: "https://fedoraproject.org/wiki/Licensing/Xinetd_License", + osiApproved: false, }, "BSD-4-Clause": { - "name": "BSD 4-Clause \"Original\" or \"Old\" License", - "url": "http://directory.fsf.org/wiki/License:BSD_4Clause", - "osiApproved": false + name: 'BSD 4-Clause "Original" or "Old" License', + url: "http://directory.fsf.org/wiki/License:BSD_4Clause", + osiApproved: false, }, "IBM-pibs": { - "name": "IBM PowerPC Initialization and Boot Software", - "url": "http://git.denx.de/?p=u-boot.git;a=blob;f=arch/powerpc/cpu/ppc4xx/miiphy.c;h=297155fdafa064b955e53e9832de93bfb0cfb85b;hb=9fab4bf4cc077c21e43941866f3f2c196f28670d", - "osiApproved": false + name: "IBM PowerPC Initialization and Boot Software", + url: "http://git.denx.de/?p=u-boot.git;a=blob;f=arch/powerpc/cpu/ppc4xx/miiphy.c;h=297155fdafa064b955e53e9832de93bfb0cfb85b;hb=9fab4bf4cc077c21e43941866f3f2c196f28670d", + osiApproved: false, }, "Apache-2.0": { - "name": "Apache License 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0", - "osiApproved": true + name: "Apache License 2.0", + url: "https://www.apache.org/licenses/LICENSE-2.0", + osiApproved: true, }, "Linux-man-pages-1-para": { - "name": "Linux man-pages - 1 paragraph", - "url": "https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/getcpu.2#n4", - "osiApproved": false + name: "Linux man-pages - 1 paragraph", + url: "https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/getcpu.2#n4", + osiApproved: false, }, "CPOL-1.02": { - "name": "Code Project Open License 1.02", - "url": "http://www.codeproject.com/info/cpol10.aspx", - "osiApproved": false + name: "Code Project Open License 1.02", + url: "http://www.codeproject.com/info/cpol10.aspx", + osiApproved: false, }, "BSD-Source-beginning-file": { - "name": "BSD Source Code Attribution - beginning of file variant", - "url": "https://github.com/lattera/freebsd/blob/master/sys/cam/cam.c#L4", - "osiApproved": false + name: "BSD Source Code Attribution - beginning of file variant", + url: "https://github.com/lattera/freebsd/blob/master/sys/cam/cam.c#L4", + osiApproved: false, }, "CERN-OHL-P-2.0": { - "name": "CERN Open Hardware Licence Version 2 - Permissive", - "url": "https://www.ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2", - "osiApproved": true + name: "CERN Open Hardware Licence Version 2 - Permissive", + url: "https://www.ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2", + osiApproved: true, }, - "OFFIS": { - "name": "OFFIS License", - "url": "https://sourceforge.net/p/xmedcon/code/ci/master/tree/libs/dicom/README", - "osiApproved": false + OFFIS: { + name: "OFFIS License", + url: "https://sourceforge.net/p/xmedcon/code/ci/master/tree/libs/dicom/README", + osiApproved: false, }, "GPL-2.0-or-later": { - "name": "GNU General Public License v2.0 or later", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v2.0 or later", + url: "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", + osiApproved: true, }, - "radvd": { - "name": "radvd License", - "url": "https://github.com/radvd-project/radvd/blob/master/COPYRIGHT", - "osiApproved": false + radvd: { + name: "radvd License", + url: "https://github.com/radvd-project/radvd/blob/master/COPYRIGHT", + osiApproved: false, }, - "Xfig": { - "name": "Xfig License", - "url": "https://github.com/Distrotech/transfig/blob/master/transfig/transfig.c", - "osiApproved": false + Xfig: { + name: "Xfig License", + url: "https://github.com/Distrotech/transfig/blob/master/transfig/transfig.c", + osiApproved: false, }, - "Multics": { - "name": "Multics License", - "url": "https://opensource.org/licenses/Multics", - "osiApproved": true + Multics: { + name: "Multics License", + url: "https://opensource.org/licenses/Multics", + osiApproved: true, }, "AFL-1.1": { - "name": "Academic Free License v1.1", - "url": "http://opensource.linux-mirror.org/licenses/afl-1.1.txt", - "osiApproved": true + name: "Academic Free License v1.1", + url: "http://opensource.linux-mirror.org/licenses/afl-1.1.txt", + osiApproved: true, }, - "Beerware": { - "name": "Beerware License", - "url": "https://fedoraproject.org/wiki/Licensing/Beerware", - "osiApproved": false + Beerware: { + name: "Beerware License", + url: "https://fedoraproject.org/wiki/Licensing/Beerware", + osiApproved: false, }, "MS-PL": { - "name": "Microsoft Public License", - "url": "http://www.microsoft.com/opensource/licenses.mspx", - "osiApproved": true + name: "Microsoft Public License", + url: "http://www.microsoft.com/opensource/licenses.mspx", + osiApproved: true, }, "ssh-keyscan": { - "name": "ssh-keyscan License", - "url": "https://github.com/openssh/openssh-portable/blob/master/LICENCE#L82", - "osiApproved": false + name: "ssh-keyscan License", + url: "https://github.com/openssh/openssh-portable/blob/master/LICENCE#L82", + osiApproved: false, }, "Spencer-99": { - "name": "Spencer License 99", - "url": "http://www.opensource.apple.com/source/tcl/tcl-5/tcl/generic/regfronts.c", - "osiApproved": false + name: "Spencer License 99", + url: "http://www.opensource.apple.com/source/tcl/tcl-5/tcl/generic/regfronts.c", + osiApproved: false, }, "OFL-1.1": { - "name": "SIL Open Font License 1.1", - "url": "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web", - "osiApproved": true + name: "SIL Open Font License 1.1", + url: "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web", + osiApproved: true, }, - "Baekmuk": { - "name": "Baekmuk License", - "url": "https://fedoraproject.org/wiki/Licensing:Baekmuk?rd=Licensing/Baekmuk", - "osiApproved": false + Baekmuk: { + name: "Baekmuk License", + url: "https://fedoraproject.org/wiki/Licensing:Baekmuk?rd=Licensing/Baekmuk", + osiApproved: false, }, - "Qhull": { - "name": "Qhull License", - "url": "https://fedoraproject.org/wiki/Licensing/Qhull", - "osiApproved": false + Qhull: { + name: "Qhull License", + url: "https://fedoraproject.org/wiki/Licensing/Qhull", + osiApproved: false, }, "GFDL-1.2-or-later": { - "name": "GNU Free Documentation License v1.2 or later", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2 or later", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, "CC-BY-NC-SA-4.0": { - "name": "Creative Commons Attribution Non Commercial Share Alike 4.0 International", - "url": "https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 4.0 International", + url: "https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode", + osiApproved: false, }, "APSL-2.0": { - "name": "Apple Public Source License 2.0", - "url": "http://www.opensource.apple.com/license/apsl/", - "osiApproved": true + name: "Apple Public Source License 2.0", + url: "http://www.opensource.apple.com/license/apsl/", + osiApproved: true, }, - "VOSTROM": { - "name": "VOSTROM Public License for Open Source", - "url": "https://fedoraproject.org/wiki/Licensing/VOSTROM", - "osiApproved": false + VOSTROM: { + name: "VOSTROM Public License for Open Source", + url: "https://fedoraproject.org/wiki/Licensing/VOSTROM", + osiApproved: false, }, "Net-SNMP": { - "name": "Net-SNMP License", - "url": "http://net-snmp.sourceforge.net/about/license.html", - "osiApproved": false + name: "Net-SNMP License", + url: "http://net-snmp.sourceforge.net/about/license.html", + osiApproved: false, }, "HPND-doc": { - "name": "Historical Permission Notice and Disclaimer - documentation variant", - "url": "https://gitlab.freedesktop.org/xorg/lib/libxext/-/blob/master/COPYING?ref_type=heads#L185-197", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - documentation variant", + url: "https://gitlab.freedesktop.org/xorg/lib/libxext/-/blob/master/COPYING?ref_type=heads#L185-197", + osiApproved: false, }, - "NRL": { - "name": "NRL License", - "url": "http://web.mit.edu/network/isakmp/nrllicense.html", - "osiApproved": false + NRL: { + name: "NRL License", + url: "http://web.mit.edu/network/isakmp/nrllicense.html", + osiApproved: false, }, - "TPDL": { - "name": "Time::ParseDate License", - "url": "https://metacpan.org/pod/Time::ParseDate#LICENSE", - "osiApproved": false + TPDL: { + name: "Time::ParseDate License", + url: "https://metacpan.org/pod/Time::ParseDate#LICENSE", + osiApproved: false, }, "AGPL-1.0-or-later": { - "name": "Affero General Public License v1.0 or later", - "url": "http://www.affero.org/oagpl.html", - "osiApproved": false + name: "Affero General Public License v1.0 or later", + url: "http://www.affero.org/oagpl.html", + osiApproved: false, }, "HPND-Markus-Kuhn": { - "name": "Historical Permission Notice and Disclaimer - Markus Kuhn variant", - "url": "https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - Markus Kuhn variant", + url: "https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c", + osiApproved: false, }, "LZMA-SDK-9.22": { - "name": "LZMA SDK License (versions 9.22 and beyond)", - "url": "https://www.7-zip.org/sdk.html", - "osiApproved": false + name: "LZMA SDK License (versions 9.22 and beyond)", + url: "https://www.7-zip.org/sdk.html", + osiApproved: false, }, "Unicode-3.0": { - "name": "Unicode License v3", - "url": "https://www.unicode.org/license.txt", - "osiApproved": true + name: "Unicode License v3", + url: "https://www.unicode.org/license.txt", + osiApproved: true, }, "GPL-3.0-or-later": { - "name": "GNU General Public License v3.0 or later", - "url": "https://www.gnu.org/licenses/gpl-3.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v3.0 or later", + url: "https://www.gnu.org/licenses/gpl-3.0-standalone.html", + osiApproved: true, }, "OpenSSL-standalone": { - "name": "OpenSSL License - standalone", - "url": "https://library.netapp.com/ecm/ecm_download_file/ECMP1196395", - "osiApproved": false + name: "OpenSSL License - standalone", + url: "https://library.netapp.com/ecm/ecm_download_file/ECMP1196395", + osiApproved: false, }, "Zimbra-1.3": { - "name": "Zimbra Public License v1.3", - "url": "http://web.archive.org/web/20100302225219/http://www.zimbra.com/license/zimbra-public-license-1-3.html", - "osiApproved": false + name: "Zimbra Public License v1.3", + url: "http://web.archive.org/web/20100302225219/http://www.zimbra.com/license/zimbra-public-license-1-3.html", + osiApproved: false, }, "xkeyboard-config-Zinoviev": { - "name": "xkeyboard-config Zinoviev License", - "url": "https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/blob/master/COPYING?ref_type=heads#L178", - "osiApproved": false + name: "xkeyboard-config Zinoviev License", + url: "https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/blob/master/COPYING?ref_type=heads#L178", + osiApproved: false, }, "GFDL-1.1-invariants-only": { - "name": "GNU Free Documentation License v1.1 only - invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1 only - invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, - "OML": { - "name": "Open Market License", - "url": "https://fedoraproject.org/wiki/Licensing/Open_Market_License", - "osiApproved": false + OML: { + name: "Open Market License", + url: "https://fedoraproject.org/wiki/Licensing/Open_Market_License", + osiApproved: false, }, "ANTLR-PD": { - "name": "ANTLR Software Rights Notice", - "url": "http://www.antlr2.org/license.html", - "osiApproved": false + name: "ANTLR Software Rights Notice", + url: "http://www.antlr2.org/license.html", + osiApproved: false, }, "HPND-MIT-disclaimer": { - "name": "Historical Permission Notice and Disclaimer with MIT disclaimer", - "url": "https://metacpan.org/release/NLNETLABS/Net-DNS-SEC-1.22/source/LICENSE", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer with MIT disclaimer", + url: "https://metacpan.org/release/NLNETLABS/Net-DNS-SEC-1.22/source/LICENSE", + osiApproved: false, }, - "Dotseqn": { - "name": "Dotseqn License", - "url": "https://fedoraproject.org/wiki/Licensing/Dotseqn", - "osiApproved": false + Dotseqn: { + name: "Dotseqn License", + url: "https://fedoraproject.org/wiki/Licensing/Dotseqn", + osiApproved: false, }, "HPND-DEC": { - "name": "Historical Permission Notice and Disclaimer - DEC variant", - "url": "https://gitlab.freedesktop.org/xorg/app/xkbcomp/-/blob/master/COPYING?ref_type=heads#L69", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - DEC variant", + url: "https://gitlab.freedesktop.org/xorg/app/xkbcomp/-/blob/master/COPYING?ref_type=heads#L69", + osiApproved: false, }, "LGPL-2.0-only": { - "name": "GNU Library General Public License v2 only", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", - "osiApproved": true + name: "GNU Library General Public License v2 only", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", + osiApproved: true, }, "CC-BY-2.5-AU": { - "name": "Creative Commons Attribution 2.5 Australia", - "url": "https://creativecommons.org/licenses/by/2.5/au/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 2.5 Australia", + url: "https://creativecommons.org/licenses/by/2.5/au/legalcode", + osiApproved: false, }, "DEC-3-Clause": { - "name": "DEC 3-Clause License", - "url": "https://gitlab.freedesktop.org/xorg/xserver/-/blob/master/COPYING?ref_type=heads#L239", - "osiApproved": false + name: "DEC 3-Clause License", + url: "https://gitlab.freedesktop.org/xorg/xserver/-/blob/master/COPYING?ref_type=heads#L239", + osiApproved: false, }, "QPL-1.0-INRIA-2004": { - "name": "Q Public License 1.0 - INRIA 2004 variant", - "url": "https://github.com/maranget/hevea/blob/master/LICENSE", - "osiApproved": false + name: "Q Public License 1.0 - INRIA 2004 variant", + url: "https://github.com/maranget/hevea/blob/master/LICENSE", + osiApproved: false, }, - "Intel": { - "name": "Intel Open Source License", - "url": "https://opensource.org/licenses/Intel", - "osiApproved": true + Intel: { + name: "Intel Open Source License", + url: "https://opensource.org/licenses/Intel", + osiApproved: true, }, "NIST-PD-fallback": { - "name": "NIST Public Domain Notice with license fallback", - "url": "https://github.com/usnistgov/jsip/blob/59700e6926cbe96c5cdae897d9a7d2656b42abe3/LICENSE", - "osiApproved": false + name: "NIST Public Domain Notice with license fallback", + url: "https://github.com/usnistgov/jsip/blob/59700e6926cbe96c5cdae897d9a7d2656b42abe3/LICENSE", + osiApproved: false, }, "CC-BY-NC-4.0": { - "name": "Creative Commons Attribution Non Commercial 4.0 International", - "url": "https://creativecommons.org/licenses/by-nc/4.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial 4.0 International", + url: "https://creativecommons.org/licenses/by-nc/4.0/legalcode", + osiApproved: false, }, "BSD-3-Clause-No-Nuclear-Warranty": { - "name": "BSD 3-Clause No Nuclear Warranty", - "url": "https://jogamp.org/git/?p=gluegen.git;a=blob_plain;f=LICENSE.txt", - "osiApproved": false + name: "BSD 3-Clause No Nuclear Warranty", + url: "https://jogamp.org/git/?p=gluegen.git;a=blob_plain;f=LICENSE.txt", + osiApproved: false, }, "HPND-UC": { - "name": "Historical Permission Notice and Disclaimer - University of California variant", - "url": "https://core.tcl-lang.org/tk/file?name=compat/unistd.h", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - University of California variant", + url: "https://core.tcl-lang.org/tk/file?name=compat/unistd.h", + osiApproved: false, }, "MIT-Wu": { - "name": "MIT Tom Wu Variant", - "url": "https://github.com/chromium/octane/blob/master/crypto.js", - "osiApproved": false + name: "MIT Tom Wu Variant", + url: "https://github.com/chromium/octane/blob/master/crypto.js", + osiApproved: false, }, - "Kastrup": { - "name": "Kastrup License", - "url": "https://ctan.math.utah.edu/ctan/tex-archive/macros/generic/kastrup/binhex.dtx", - "osiApproved": false + Kastrup: { + name: "Kastrup License", + url: "https://ctan.math.utah.edu/ctan/tex-archive/macros/generic/kastrup/binhex.dtx", + osiApproved: false, }, "MIT-CMU": { - "name": "CMU License", - "url": "https://fedoraproject.org/wiki/Licensing:MIT?rd=Licensing/MIT#CMU_Style", - "osiApproved": false + name: "CMU License", + url: "https://fedoraproject.org/wiki/Licensing:MIT?rd=Licensing/MIT#CMU_Style", + osiApproved: false, }, "DL-DE-ZERO-2.0": { - "name": "Data licence Germany – zero – version 2.0", - "url": "https://www.govdata.de/dl-de/zero-2-0", - "osiApproved": false + name: "Data licence Germany – zero – version 2.0", + url: "https://www.govdata.de/dl-de/zero-2-0", + osiApproved: false, }, "NIST-Software": { - "name": "NIST Software License", - "url": "https://github.com/open-quantum-safe/liboqs/blob/40b01fdbb270f8614fde30e65d30e9da18c02393/src/common/rand/rand_nist.c#L1-L15", - "osiApproved": false + name: "NIST Software License", + url: "https://github.com/open-quantum-safe/liboqs/blob/40b01fdbb270f8614fde30e65d30e9da18c02393/src/common/rand/rand_nist.c#L1-L15", + osiApproved: false, }, "Spencer-94": { - "name": "Spencer License 94", - "url": "https://fedoraproject.org/wiki/Licensing/Henry_Spencer_Reg-Ex_Library_License", - "osiApproved": false + name: "Spencer License 94", + url: "https://fedoraproject.org/wiki/Licensing/Henry_Spencer_Reg-Ex_Library_License", + osiApproved: false, }, "CC-BY-2.0": { - "name": "Creative Commons Attribution 2.0 Generic", - "url": "https://creativecommons.org/licenses/by/2.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 2.0 Generic", + url: "https://creativecommons.org/licenses/by/2.0/legalcode", + osiApproved: false, }, "EUPL-1.1": { - "name": "European Union Public License 1.1", - "url": "https://joinup.ec.europa.eu/software/page/eupl/licence-eupl", - "osiApproved": true + name: "European Union Public License 1.1", + url: "https://joinup.ec.europa.eu/software/page/eupl/licence-eupl", + osiApproved: true, }, "HPND-export-US-modify": { - "name": "HPND with US Government export control warning and modification rqmt", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L1157-L1182", - "osiApproved": false + name: "HPND with US Government export control warning and modification rqmt", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L1157-L1182", + osiApproved: false, }, "generic-xts": { - "name": "Generic XTS License", - "url": "https://github.com/mhogomchungu/zuluCrypt/blob/master/external_libraries/tcplay/generic_xts.c", - "osiApproved": false + name: "Generic XTS License", + url: "https://github.com/mhogomchungu/zuluCrypt/blob/master/external_libraries/tcplay/generic_xts.c", + osiApproved: false, }, - "NLPL": { - "name": "No Limit Public License", - "url": "https://fedoraproject.org/wiki/Licensing/NLPL", - "osiApproved": false + NLPL: { + name: "No Limit Public License", + url: "https://fedoraproject.org/wiki/Licensing/NLPL", + osiApproved: false, }, - "NCSA": { - "name": "University of Illinois/NCSA Open Source License", - "url": "http://otm.illinois.edu/uiuc_openSource", - "osiApproved": true + NCSA: { + name: "University of Illinois/NCSA Open Source License", + url: "http://otm.illinois.edu/uiuc_openSource", + osiApproved: true, }, "PSF-2.0": { - "name": "Python Software Foundation License 2.0", - "url": "https://opensource.org/licenses/Python-2.0", - "osiApproved": false + name: "Python Software Foundation License 2.0", + url: "https://opensource.org/licenses/Python-2.0", + osiApproved: false, }, "Linux-man-pages-copyleft-var": { - "name": "Linux man-pages Copyleft Variant", - "url": "https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/set_mempolicy.2#n5", - "osiApproved": false + name: "Linux man-pages Copyleft Variant", + url: "https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/set_mempolicy.2#n5", + osiApproved: false, }, "OSL-1.1": { - "name": "Open Software License 1.1", - "url": "https://fedoraproject.org/wiki/Licensing/OSL1.1", - "osiApproved": false + name: "Open Software License 1.1", + url: "https://fedoraproject.org/wiki/Licensing/OSL1.1", + osiApproved: false, }, "mpi-permissive": { - "name": "mpi Permissive License", - "url": "https://sources.debian.org/src/openmpi/4.1.0-10/ompi/debuggers/msgq_interface.h/?hl=19#L19", - "osiApproved": false + name: "mpi Permissive License", + url: "https://sources.debian.org/src/openmpi/4.1.0-10/ompi/debuggers/msgq_interface.h/?hl=19#L19", + osiApproved: false, }, - "Glulxe": { - "name": "Glulxe License", - "url": "https://fedoraproject.org/wiki/Licensing/Glulxe", - "osiApproved": false + Glulxe: { + name: "Glulxe License", + url: "https://fedoraproject.org/wiki/Licensing/Glulxe", + osiApproved: false, }, "LAL-1.2": { - "name": "Licence Art Libre 1.2", - "url": "http://artlibre.org/licence/lal/licence-art-libre-12/", - "osiApproved": false + name: "Licence Art Libre 1.2", + url: "http://artlibre.org/licence/lal/licence-art-libre-12/", + osiApproved: false, }, "SMAIL-GPL": { - "name": "SMAIL General Public License", - "url": "https://sources.debian.org/copyright/license/debianutils/4.11.2/", - "osiApproved": false + name: "SMAIL General Public License", + url: "https://sources.debian.org/copyright/license/debianutils/4.11.2/", + osiApproved: false, }, "NASA-1.3": { - "name": "NASA Open Source Agreement 1.3", - "url": "http://ti.arc.nasa.gov/opensource/nosa/", - "osiApproved": true + name: "NASA Open Source Agreement 1.3", + url: "http://ti.arc.nasa.gov/opensource/nosa/", + osiApproved: true, }, "SPL-1.0": { - "name": "Sun Public License v1.0", - "url": "https://opensource.org/licenses/SPL-1.0", - "osiApproved": true + name: "Sun Public License v1.0", + url: "https://opensource.org/licenses/SPL-1.0", + osiApproved: true, }, "BSD-Advertising-Acknowledgement": { - "name": "BSD Advertising Acknowledgement License", - "url": "https://github.com/python-excel/xlrd/blob/master/LICENSE#L33", - "osiApproved": false + name: "BSD Advertising Acknowledgement License", + url: "https://github.com/python-excel/xlrd/blob/master/LICENSE#L33", + osiApproved: false, }, "BSD-3-Clause-Modification": { - "name": "BSD 3-Clause Modification", - "url": "https://fedoraproject.org/wiki/Licensing:BSD#Modification_Variant", - "osiApproved": false + name: "BSD 3-Clause Modification", + url: "https://fedoraproject.org/wiki/Licensing:BSD#Modification_Variant", + osiApproved: false, }, "3D-Slicer-1.0": { - "name": "3D Slicer License v1.0", - "url": "https://slicer.org/LICENSE", - "osiApproved": false + name: "3D Slicer License v1.0", + url: "https://slicer.org/LICENSE", + osiApproved: false, }, "NPL-1.1": { - "name": "Netscape Public License v1.1", - "url": "http://www.mozilla.org/MPL/NPL/1.1/", - "osiApproved": false + name: "Netscape Public License v1.1", + url: "http://www.mozilla.org/MPL/NPL/1.1/", + osiApproved: false, }, "GPL-2.0-with-GCC-exception": { - "name": "GNU General Public License v2.0 w/GCC Runtime Library exception", - "url": "https://gcc.gnu.org/git/?p=gcc.git;a=blob;f=gcc/libgcc1.c;h=762f5143fc6eed57b6797c82710f3538aa52b40b;hb=cb143a3ce4fb417c68f5fa2691a1b1b1053dfba9#l10", - "osiApproved": false + name: "GNU General Public License v2.0 w/GCC Runtime Library exception", + url: "https://gcc.gnu.org/git/?p=gcc.git;a=blob;f=gcc/libgcc1.c;h=762f5143fc6eed57b6797c82710f3538aa52b40b;hb=cb143a3ce4fb417c68f5fa2691a1b1b1053dfba9#l10", + osiApproved: false, }, "IJG-short": { - "name": "Independent JPEG Group License - short", - "url": "https://sourceforge.net/p/xmedcon/code/ci/master/tree/libs/ljpg/", - "osiApproved": false + name: "Independent JPEG Group License - short", + url: "https://sourceforge.net/p/xmedcon/code/ci/master/tree/libs/ljpg/", + osiApproved: false, }, "CC-BY-4.0": { - "name": "Creative Commons Attribution 4.0 International", - "url": "https://creativecommons.org/licenses/by/4.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 4.0 International", + url: "https://creativecommons.org/licenses/by/4.0/legalcode", + osiApproved: false, }, - "ulem": { - "name": "ulem License", - "url": "https://mirrors.ctan.org/macros/latex/contrib/ulem/README", - "osiApproved": false + ulem: { + name: "ulem License", + url: "https://mirrors.ctan.org/macros/latex/contrib/ulem/README", + osiApproved: false, }, "BSD-3-Clause-Sun": { - "name": "BSD 3-Clause Sun Microsystems", - "url": "https://github.com/xmlark/msv/blob/b9316e2f2270bc1606952ea4939ec87fbba157f3/xsdlib/src/main/java/com/sun/msv/datatype/regexp/InternalImpl.java", - "osiApproved": false + name: "BSD 3-Clause Sun Microsystems", + url: "https://github.com/xmlark/msv/blob/b9316e2f2270bc1606952ea4939ec87fbba157f3/xsdlib/src/main/java/com/sun/msv/datatype/regexp/InternalImpl.java", + osiApproved: false, }, "SAX-PD-2.0": { - "name": "Sax Public Domain Notice 2.0", - "url": "http://www.saxproject.org/copying.html", - "osiApproved": false + name: "Sax Public Domain Notice 2.0", + url: "http://www.saxproject.org/copying.html", + osiApproved: false, }, "TORQUE-1.1": { - "name": "TORQUE v2.5+ Software License v1.1", - "url": "https://fedoraproject.org/wiki/Licensing/TORQUEv1.1", - "osiApproved": false + name: "TORQUE v2.5+ Software License v1.1", + url: "https://fedoraproject.org/wiki/Licensing/TORQUEv1.1", + osiApproved: false, }, "TU-Berlin-2.0": { - "name": "Technische Universitaet Berlin License 2.0", - "url": "https://github.com/CorsixTH/deps/blob/fd339a9f526d1d9c9f01ccf39e438a015da50035/licences/libgsm.txt", - "osiApproved": false + name: "Technische Universitaet Berlin License 2.0", + url: "https://github.com/CorsixTH/deps/blob/fd339a9f526d1d9c9f01ccf39e438a015da50035/licences/libgsm.txt", + osiApproved: false, }, - "Borceux": { - "name": "Borceux license", - "url": "https://fedoraproject.org/wiki/Licensing/Borceux", - "osiApproved": false + Borceux: { + name: "Borceux license", + url: "https://fedoraproject.org/wiki/Licensing/Borceux", + osiApproved: false, }, "GPL-3.0+": { - "name": "GNU General Public License v3.0 or later", - "url": "https://www.gnu.org/licenses/gpl-3.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v3.0 or later", + url: "https://www.gnu.org/licenses/gpl-3.0-standalone.html", + osiApproved: true, }, "0BSD": { - "name": "BSD Zero Clause License", - "url": "http://landley.net/toybox/license.html", - "osiApproved": true + name: "BSD Zero Clause License", + url: "http://landley.net/toybox/license.html", + osiApproved: true, }, "Mackerras-3-Clause": { - "name": "Mackerras 3-Clause License", - "url": "https://github.com/ppp-project/ppp/blob/master/pppd/chap_ms.c#L6-L28", - "osiApproved": false + name: "Mackerras 3-Clause License", + url: "https://github.com/ppp-project/ppp/blob/master/pppd/chap_ms.c#L6-L28", + osiApproved: false, }, "GFDL-1.3-invariants-or-later": { - "name": "GNU Free Documentation License v1.3 or later - invariants", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3 or later - invariants", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, "Knuth-CTAN": { - "name": "Knuth CTAN License", - "url": "https://ctan.org/license/knuth", - "osiApproved": false + name: "Knuth CTAN License", + url: "https://ctan.org/license/knuth", + osiApproved: false, }, - "SMLNJ": { - "name": "Standard ML of New Jersey License", - "url": "https://www.smlnj.org/license.html", - "osiApproved": false + SMLNJ: { + name: "Standard ML of New Jersey License", + url: "https://www.smlnj.org/license.html", + osiApproved: false, }, "NPOSL-3.0": { - "name": "Non-Profit Open Software License 3.0", - "url": "https://opensource.org/licenses/NOSL3.0", - "osiApproved": true + name: "Non-Profit Open Software License 3.0", + url: "https://opensource.org/licenses/NOSL3.0", + osiApproved: true, }, "OLDAP-1.4": { - "name": "Open LDAP Public License v1.4", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=c9f95c2f3f2ffb5e0ae55fe7388af75547660941", - "osiApproved": false + name: "Open LDAP Public License v1.4", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=c9f95c2f3f2ffb5e0ae55fe7388af75547660941", + osiApproved: false, }, "Intel-ACPI": { - "name": "Intel ACPI Software License Agreement", - "url": "https://fedoraproject.org/wiki/Licensing/Intel_ACPI_Software_License_Agreement", - "osiApproved": false + name: "Intel ACPI Software License Agreement", + url: "https://fedoraproject.org/wiki/Licensing/Intel_ACPI_Software_License_Agreement", + osiApproved: false, }, "Adobe-Glyph": { - "name": "Adobe Glyph List License", - "url": "https://fedoraproject.org/wiki/Licensing/MIT#AdobeGlyph", - "osiApproved": false + name: "Adobe Glyph List License", + url: "https://fedoraproject.org/wiki/Licensing/MIT#AdobeGlyph", + osiApproved: false, }, "BSD-3-Clause-Attribution": { - "name": "BSD with attribution", - "url": "https://fedoraproject.org/wiki/Licensing/BSD_with_Attribution", - "osiApproved": false + name: "BSD with attribution", + url: "https://fedoraproject.org/wiki/Licensing/BSD_with_Attribution", + osiApproved: false, }, - "metamail": { - "name": "metamail License", - "url": "https://github.com/Dual-Life/mime-base64/blob/master/Base64.xs#L12", - "osiApproved": false + metamail: { + name: "metamail License", + url: "https://github.com/Dual-Life/mime-base64/blob/master/Base64.xs#L12", + osiApproved: false, }, - "Zed": { - "name": "Zed License", - "url": "https://fedoraproject.org/wiki/Licensing/Zed", - "osiApproved": false + Zed: { + name: "Zed License", + url: "https://fedoraproject.org/wiki/Licensing/Zed", + osiApproved: false, }, "Sun-PPP-2000": { - "name": "Sun PPP License (2000)", - "url": "https://github.com/ppp-project/ppp/blob/master/modules/ppp_ahdlc.c#L7-L19", - "osiApproved": false + name: "Sun PPP License (2000)", + url: "https://github.com/ppp-project/ppp/blob/master/modules/ppp_ahdlc.c#L7-L19", + osiApproved: false, }, "SGI-B-1.0": { - "name": "SGI Free Software License B v1.0", - "url": "http://oss.sgi.com/projects/FreeB/SGIFreeSWLicB.1.0.html", - "osiApproved": false + name: "SGI Free Software License B v1.0", + url: "http://oss.sgi.com/projects/FreeB/SGIFreeSWLicB.1.0.html", + osiApproved: false, }, - "xlock": { - "name": "xlock License", - "url": "https://fossies.org/linux/tiff/contrib/ras/ras2tif.c", - "osiApproved": false + xlock: { + name: "xlock License", + url: "https://fossies.org/linux/tiff/contrib/ras/ras2tif.c", + osiApproved: false, }, "AGPL-3.0": { - "name": "GNU Affero General Public License v3.0", - "url": "https://www.gnu.org/licenses/agpl.txt", - "osiApproved": true + name: "GNU Affero General Public License v3.0", + url: "https://www.gnu.org/licenses/agpl.txt", + osiApproved: true, }, - "SCEA": { - "name": "SCEA Shared Source License", - "url": "http://research.scea.com/scea_shared_source_license.html", - "osiApproved": false + SCEA: { + name: "SCEA Shared Source License", + url: "http://research.scea.com/scea_shared_source_license.html", + osiApproved: false, }, "Artistic-2.0": { - "name": "Artistic License 2.0", - "url": "http://www.perlfoundation.org/artistic_license_2_0", - "osiApproved": true + name: "Artistic License 2.0", + url: "http://www.perlfoundation.org/artistic_license_2_0", + osiApproved: true, }, - "ICU": { - "name": "ICU License", - "url": "http://source.icu-project.org/repos/icu/icu/trunk/license.html", - "osiApproved": true + ICU: { + name: "ICU License", + url: "http://source.icu-project.org/repos/icu/icu/trunk/license.html", + osiApproved: true, }, "CC-BY-2.5": { - "name": "Creative Commons Attribution 2.5 Generic", - "url": "https://creativecommons.org/licenses/by/2.5/legalcode", - "osiApproved": false + name: "Creative Commons Attribution 2.5 Generic", + url: "https://creativecommons.org/licenses/by/2.5/legalcode", + osiApproved: false, }, "SHL-0.51": { - "name": "Solderpad Hardware License, Version 0.51", - "url": "https://solderpad.org/licenses/SHL-0.51/", - "osiApproved": false + name: "Solderpad Hardware License, Version 0.51", + url: "https://solderpad.org/licenses/SHL-0.51/", + osiApproved: false, }, "LPPL-1.3a": { - "name": "LaTeX Project Public License v1.3a", - "url": "http://www.latex-project.org/lppl/lppl-1-3a.txt", - "osiApproved": false + name: "LaTeX Project Public License v1.3a", + url: "http://www.latex-project.org/lppl/lppl-1-3a.txt", + osiApproved: false, }, "CDLA-Permissive-1.0": { - "name": "Community Data License Agreement Permissive 1.0", - "url": "https://cdla.io/permissive-1-0", - "osiApproved": false + name: "Community Data License Agreement Permissive 1.0", + url: "https://cdla.io/permissive-1-0", + osiApproved: false, }, "EFL-2.0": { - "name": "Eiffel Forum License v2.0", - "url": "http://www.eiffel-nice.org/license/eiffel-forum-license-2.html", - "osiApproved": true + name: "Eiffel Forum License v2.0", + url: "http://www.eiffel-nice.org/license/eiffel-forum-license-2.html", + osiApproved: true, }, "URT-RLE": { - "name": "Utah Raster Toolkit Run Length Encoded License", - "url": "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/converter/other/pnmtorle.c", - "osiApproved": false + name: "Utah Raster Toolkit Run Length Encoded License", + url: "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/converter/other/pnmtorle.c", + osiApproved: false, }, "HPND-sell-regexpr": { - "name": "Historical Permission Notice and Disclaimer - sell regexpr variant", - "url": "https://gitlab.com/bacula-org/bacula/-/blob/Branch-11.0/bacula/LICENSE-FOSS?ref_type=heads#L245", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - sell regexpr variant", + url: "https://gitlab.com/bacula-org/bacula/-/blob/Branch-11.0/bacula/LICENSE-FOSS?ref_type=heads#L245", + osiApproved: false, }, "GFDL-1.3-no-invariants-or-later": { - "name": "GNU Free Documentation License v1.3 or later - no invariants", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3 or later - no invariants", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, - "AMDPLPA": { - "name": "AMD's plpa_map.c License", - "url": "https://fedoraproject.org/wiki/Licensing/AMD_plpa_map_License", - "osiApproved": false + AMDPLPA: { + name: "AMD's plpa_map.c License", + url: "https://fedoraproject.org/wiki/Licensing/AMD_plpa_map_License", + osiApproved: false, }, "Bitstream-Charter": { - "name": "Bitstream Charter Font License", - "url": "https://fedoraproject.org/wiki/Licensing/Charter#License_Text", - "osiApproved": false + name: "Bitstream Charter Font License", + url: "https://fedoraproject.org/wiki/Licensing/Charter#License_Text", + osiApproved: false, }, "python-ldap": { - "name": "Python ldap License", - "url": "https://github.com/python-ldap/python-ldap/blob/main/LICENCE", - "osiApproved": false + name: "Python ldap License", + url: "https://github.com/python-ldap/python-ldap/blob/main/LICENCE", + osiApproved: false, }, "CC-BY-SA-3.0-AT": { - "name": "Creative Commons Attribution Share Alike 3.0 Austria", - "url": "https://creativecommons.org/licenses/by-sa/3.0/at/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 3.0 Austria", + url: "https://creativecommons.org/licenses/by-sa/3.0/at/legalcode", + osiApproved: false, }, "OGC-1.0": { - "name": "OGC Software License, Version 1.0", - "url": "https://www.ogc.org/ogc/software/1.0", - "osiApproved": false + name: "OGC Software License, Version 1.0", + url: "https://www.ogc.org/ogc/software/1.0", + osiApproved: false, }, "CC-BY-SA-2.0": { - "name": "Creative Commons Attribution Share Alike 2.0 Generic", - "url": "https://creativecommons.org/licenses/by-sa/2.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 2.0 Generic", + url: "https://creativecommons.org/licenses/by-sa/2.0/legalcode", + osiApproved: false, }, - "PADL": { - "name": "PADL License", - "url": "https://git.openldap.org/openldap/openldap/-/blob/master/libraries/libldap/os-local.c?ref_type=heads#L19-23", - "osiApproved": false + PADL: { + name: "PADL License", + url: "https://git.openldap.org/openldap/openldap/-/blob/master/libraries/libldap/os-local.c?ref_type=heads#L19-23", + osiApproved: false, }, "NICTA-1.0": { - "name": "NICTA Public Software License, Version 1.0", - "url": "https://opensource.apple.com/source/mDNSResponder/mDNSResponder-320.10/mDNSPosix/nss_ReadMe.txt", - "osiApproved": false + name: "NICTA Public Software License, Version 1.0", + url: "https://opensource.apple.com/source/mDNSResponder/mDNSResponder-320.10/mDNSPosix/nss_ReadMe.txt", + osiApproved: false, }, "LPL-1.0": { - "name": "Lucent Public License Version 1.0", - "url": "https://opensource.org/licenses/LPL-1.0", - "osiApproved": true + name: "Lucent Public License Version 1.0", + url: "https://opensource.org/licenses/LPL-1.0", + osiApproved: true, }, "LPPL-1.1": { - "name": "LaTeX Project Public License v1.1", - "url": "http://www.latex-project.org/lppl/lppl-1-1.txt", - "osiApproved": false + name: "LaTeX Project Public License v1.1", + url: "http://www.latex-project.org/lppl/lppl-1-1.txt", + osiApproved: false, }, "CDL-1.0": { - "name": "Common Documentation License 1.0", - "url": "http://www.opensource.apple.com/cdl/", - "osiApproved": false + name: "Common Documentation License 1.0", + url: "http://www.opensource.apple.com/cdl/", + osiApproved: false, }, "Boehm-GC": { - "name": "Boehm-Demers-Weiser GC License", - "url": "https://fedoraproject.org/wiki/Licensing:MIT#Another_Minimal_variant_(found_in_libatomic_ops)", - "osiApproved": false + name: "Boehm-Demers-Weiser GC License", + url: "https://fedoraproject.org/wiki/Licensing:MIT#Another_Minimal_variant_(found_in_libatomic_ops)", + osiApproved: false, }, "Sun-PPP": { - "name": "Sun PPP License", - "url": "https://github.com/ppp-project/ppp/blob/master/pppd/eap.c#L7-L16", - "osiApproved": false + name: "Sun PPP License", + url: "https://github.com/ppp-project/ppp/blob/master/pppd/eap.c#L7-L16", + osiApproved: false, }, "OLDAP-2.2.1": { - "name": "Open LDAP Public License v2.2.1", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=4bc786f34b50aa301be6f5600f58a980070f481e", - "osiApproved": false + name: "Open LDAP Public License v2.2.1", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=4bc786f34b50aa301be6f5600f58a980070f481e", + osiApproved: false, }, "AGPL-3.0-or-later": { - "name": "GNU Affero General Public License v3.0 or later", - "url": "https://www.gnu.org/licenses/agpl.txt", - "osiApproved": true + name: "GNU Affero General Public License v3.0 or later", + url: "https://www.gnu.org/licenses/agpl.txt", + osiApproved: true, }, "OLDAP-2.6": { - "name": "Open LDAP Public License v2.6", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=1cae062821881f41b73012ba816434897abf4205", - "osiApproved": false + name: "Open LDAP Public License v2.6", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=1cae062821881f41b73012ba816434897abf4205", + osiApproved: false, }, "BSD-3-Clause-No-Nuclear-License": { - "name": "BSD 3-Clause No Nuclear License", - "url": "http://download.oracle.com/otn-pub/java/licenses/bsd.txt", - "osiApproved": false + name: "BSD 3-Clause No Nuclear License", + url: "http://download.oracle.com/otn-pub/java/licenses/bsd.txt", + osiApproved: false, }, "BSD-Protection": { - "name": "BSD Protection License", - "url": "https://fedoraproject.org/wiki/Licensing/BSD_Protection_License", - "osiApproved": false + name: "BSD Protection License", + url: "https://fedoraproject.org/wiki/Licensing/BSD_Protection_License", + osiApproved: false, }, "OCCT-PL": { - "name": "Open CASCADE Technology Public License", - "url": "http://www.opencascade.com/content/occt-public-license", - "osiApproved": false + name: "Open CASCADE Technology Public License", + url: "http://www.opencascade.com/content/occt-public-license", + osiApproved: false, }, "GPL-2.0-with-font-exception": { - "name": "GNU General Public License v2.0 w/Font exception", - "url": "https://www.gnu.org/licenses/gpl-faq.html#FontException", - "osiApproved": false + name: "GNU General Public License v2.0 w/Font exception", + url: "https://www.gnu.org/licenses/gpl-faq.html#FontException", + osiApproved: false, }, "YPL-1.0": { - "name": "Yahoo! Public License v1.0", - "url": "http://www.zimbra.com/license/yahoo_public_license_1.0.html", - "osiApproved": false + name: "Yahoo! Public License v1.0", + url: "http://www.zimbra.com/license/yahoo_public_license_1.0.html", + osiApproved: false, }, - "MIPS": { - "name": "MIPS License", - "url": "https://sourceware.org/cgit/binutils-gdb/tree/include/coff/sym.h#n11", - "osiApproved": false + MIPS: { + name: "MIPS License", + url: "https://sourceware.org/cgit/binutils-gdb/tree/include/coff/sym.h#n11", + osiApproved: false, }, "SGI-B-2.0": { - "name": "SGI Free Software License B v2.0", - "url": "http://oss.sgi.com/projects/FreeB/SGIFreeSWLicB.2.0.pdf", - "osiApproved": false + name: "SGI Free Software License B v2.0", + url: "http://oss.sgi.com/projects/FreeB/SGIFreeSWLicB.2.0.pdf", + osiApproved: false, }, "MIT-open-group": { - "name": "MIT Open Group variant", - "url": "https://gitlab.freedesktop.org/xorg/app/iceauth/-/blob/master/COPYING", - "osiApproved": false + name: "MIT Open Group variant", + url: "https://gitlab.freedesktop.org/xorg/app/iceauth/-/blob/master/COPYING", + osiApproved: false, }, - "AML": { - "name": "Apple MIT License", - "url": "https://fedoraproject.org/wiki/Licensing/Apple_MIT_License", - "osiApproved": false + AML: { + name: "Apple MIT License", + url: "https://fedoraproject.org/wiki/Licensing/Apple_MIT_License", + osiApproved: false, }, "OSL-1.0": { - "name": "Open Software License 1.0", - "url": "https://opensource.org/licenses/OSL-1.0", - "osiApproved": true + name: "Open Software License 1.0", + url: "https://opensource.org/licenses/OSL-1.0", + osiApproved: true, }, "GFDL-1.3-invariants-only": { - "name": "GNU Free Documentation License v1.3 only - invariants", - "url": "https://www.gnu.org/licenses/fdl-1.3.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.3 only - invariants", + url: "https://www.gnu.org/licenses/fdl-1.3.txt", + osiApproved: false, }, "bzip2-1.0.5": { - "name": "bzip2 and libbzip2 License v1.0.5", - "url": "https://sourceware.org/bzip2/1.0.5/bzip2-manual-1.0.5.html", - "osiApproved": false + name: "bzip2 and libbzip2 License v1.0.5", + url: "https://sourceware.org/bzip2/1.0.5/bzip2-manual-1.0.5.html", + osiApproved: false, }, - "Symlinks": { - "name": "Symlinks License", - "url": "https://www.mail-archive.com/debian-bugs-rc@lists.debian.org/msg11494.html", - "osiApproved": false + Symlinks: { + name: "Symlinks License", + url: "https://www.mail-archive.com/debian-bugs-rc@lists.debian.org/msg11494.html", + osiApproved: false, }, "Ruby-pty": { - "name": "Ruby pty extension license", - "url": "https://github.com/ruby/ruby/blob/9f6deaa6888a423720b4b127b5314f0ad26cc2e6/ext/pty/pty.c#L775-L786", - "osiApproved": false + name: "Ruby pty extension license", + url: "https://github.com/ruby/ruby/blob/9f6deaa6888a423720b4b127b5314f0ad26cc2e6/ext/pty/pty.c#L775-L786", + osiApproved: false, }, - "UCAR": { - "name": "UCAR License", - "url": "https://github.com/Unidata/UDUNITS-2/blob/master/COPYRIGHT", - "osiApproved": false + UCAR: { + name: "UCAR License", + url: "https://github.com/Unidata/UDUNITS-2/blob/master/COPYRIGHT", + osiApproved: false, }, "SimPL-2.0": { - "name": "Simple Public License 2.0", - "url": "https://opensource.org/licenses/SimPL-2.0", - "osiApproved": true + name: "Simple Public License 2.0", + url: "https://opensource.org/licenses/SimPL-2.0", + osiApproved: true, }, "PolyForm-Noncommercial-1.0.0": { - "name": "PolyForm Noncommercial License 1.0.0", - "url": "https://polyformproject.org/licenses/noncommercial/1.0.0", - "osiApproved": false + name: "PolyForm Noncommercial License 1.0.0", + url: "https://polyformproject.org/licenses/noncommercial/1.0.0", + osiApproved: false, }, "OFL-1.1-no-RFN": { - "name": "SIL Open Font License 1.1 with no Reserved Font Name", - "url": "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web", - "osiApproved": true + name: "SIL Open Font License 1.1 with no Reserved Font Name", + url: "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web", + osiApproved: true, }, - "Furuseth": { - "name": "Furuseth License", - "url": "https://git.openldap.org/openldap/openldap/-/blob/master/COPYRIGHT?ref_type=heads#L39-51", - "osiApproved": false + Furuseth: { + name: "Furuseth License", + url: "https://git.openldap.org/openldap/openldap/-/blob/master/COPYRIGHT?ref_type=heads#L39-51", + osiApproved: false, }, "Mackerras-3-Clause-acknowledgment": { - "name": "Mackerras 3-Clause - acknowledgment variant", - "url": "https://github.com/ppp-project/ppp/blob/master/pppd/auth.c#L6-L28", - "osiApproved": false + name: "Mackerras 3-Clause - acknowledgment variant", + url: "https://github.com/ppp-project/ppp/blob/master/pppd/auth.c#L6-L28", + osiApproved: false, }, "CC-PDM-1.0": { - "name": "Creative Commons Public Domain Mark 1.0 Universal", - "url": "https://creativecommons.org/publicdomain/mark/1.0/", - "osiApproved": false + name: "Creative Commons Public Domain Mark 1.0 Universal", + url: "https://creativecommons.org/publicdomain/mark/1.0/", + osiApproved: false, }, "LGPL-2.1+": { - "name": "GNU Lesser General Public License v2.1 or later", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v2.1 or later", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html", + osiApproved: true, }, - "Zlib": { - "name": "zlib License", - "url": "http://www.zlib.net/zlib_license.html", - "osiApproved": true + Zlib: { + name: "zlib License", + url: "http://www.zlib.net/zlib_license.html", + osiApproved: true, }, "BSD-2-Clause-Views": { - "name": "BSD 2-Clause with views sentence", - "url": "http://www.freebsd.org/copyright/freebsd-license.html", - "osiApproved": false + name: "BSD 2-Clause with views sentence", + url: "http://www.freebsd.org/copyright/freebsd-license.html", + osiApproved: false, }, "Interbase-1.0": { - "name": "Interbase Public License v1.0", - "url": "https://web.archive.org/web/20060319014854/http://info.borland.com/devsupport/interbase/opensource/IPL.html", - "osiApproved": false + name: "Interbase Public License v1.0", + url: "https://web.archive.org/web/20060319014854/http://info.borland.com/devsupport/interbase/opensource/IPL.html", + osiApproved: false, }, "LGPL-2.0": { - "name": "GNU Library General Public License v2 only", - "url": "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", - "osiApproved": true + name: "GNU Library General Public License v2 only", + url: "https://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html", + osiApproved: true, }, "LGPL-3.0-only": { - "name": "GNU Lesser General Public License v3.0 only", - "url": "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", - "osiApproved": true + name: "GNU Lesser General Public License v3.0 only", + url: "https://www.gnu.org/licenses/lgpl-3.0-standalone.html", + osiApproved: true, }, "CC-BY-NC-SA-3.0": { - "name": "Creative Commons Attribution Non Commercial Share Alike 3.0 Unported", - "url": "https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 3.0 Unported", + url: "https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode", + osiApproved: false, }, "MIT-Modern-Variant": { - "name": "MIT License Modern Variant", - "url": "https://fedoraproject.org/wiki/Licensing:MIT#Modern_Variants", - "osiApproved": true + name: "MIT License Modern Variant", + url: "https://fedoraproject.org/wiki/Licensing:MIT#Modern_Variants", + osiApproved: true, }, "Unicode-TOU": { - "name": "Unicode Terms of Use", - "url": "http://web.archive.org/web/20140704074106/http://www.unicode.org/copyright.html", - "osiApproved": false + name: "Unicode Terms of Use", + url: "http://web.archive.org/web/20140704074106/http://www.unicode.org/copyright.html", + osiApproved: false, }, - "APAFML": { - "name": "Adobe Postscript AFM License", - "url": "https://fedoraproject.org/wiki/Licensing/AdobePostscriptAFM", - "osiApproved": false + APAFML: { + name: "Adobe Postscript AFM License", + url: "https://fedoraproject.org/wiki/Licensing/AdobePostscriptAFM", + osiApproved: false, }, - "TCL": { - "name": "TCL/TK License", - "url": "http://www.tcl.tk/software/tcltk/license.html", - "osiApproved": false + TCL: { + name: "TCL/TK License", + url: "http://www.tcl.tk/software/tcltk/license.html", + osiApproved: false, }, - "Xerox": { - "name": "Xerox License", - "url": "https://fedoraproject.org/wiki/Licensing/Xerox", - "osiApproved": false + Xerox: { + name: "Xerox License", + url: "https://fedoraproject.org/wiki/Licensing/Xerox", + osiApproved: false, }, - "FSFUL": { - "name": "FSF Unlimited License", - "url": "https://fedoraproject.org/wiki/Licensing/FSF_Unlimited_License", - "osiApproved": false + FSFUL: { + name: "FSF Unlimited License", + url: "https://fedoraproject.org/wiki/Licensing/FSF_Unlimited_License", + osiApproved: false, }, "FSFAP-no-warranty-disclaimer": { - "name": "FSF All Permissive License (without Warranty)", - "url": "https://git.savannah.gnu.org/cgit/wget.git/tree/util/trunc.c?h=v1.21.3&id=40747a11e44ced5a8ac628a41f879ced3e2ebce9#n6", - "osiApproved": false + name: "FSF All Permissive License (without Warranty)", + url: "https://git.savannah.gnu.org/cgit/wget.git/tree/util/trunc.c?h=v1.21.3&id=40747a11e44ced5a8ac628a41f879ced3e2ebce9#n6", + osiApproved: false, }, "Artistic-1.0": { - "name": "Artistic License 1.0", - "url": "https://opensource.org/licenses/Artistic-1.0", - "osiApproved": true + name: "Artistic License 1.0", + url: "https://opensource.org/licenses/Artistic-1.0", + osiApproved: true, }, - "ImageMagick": { - "name": "ImageMagick License", - "url": "http://www.imagemagick.org/script/license.php", - "osiApproved": false + ImageMagick: { + name: "ImageMagick License", + url: "http://www.imagemagick.org/script/license.php", + osiApproved: false, }, "Brian-Gladman-2-Clause": { - "name": "Brian Gladman 2-Clause License", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L140-L156", - "osiApproved": false + name: "Brian Gladman 2-Clause License", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L140-L156", + osiApproved: false, }, "BitTorrent-1.1": { - "name": "BitTorrent Open Source License v1.1", - "url": "http://directory.fsf.org/wiki/License:BitTorrentOSL1.1", - "osiApproved": false + name: "BitTorrent Open Source License v1.1", + url: "http://directory.fsf.org/wiki/License:BitTorrentOSL1.1", + osiApproved: false, }, "GPL-3.0-only": { - "name": "GNU General Public License v3.0 only", - "url": "https://www.gnu.org/licenses/gpl-3.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v3.0 only", + url: "https://www.gnu.org/licenses/gpl-3.0-standalone.html", + osiApproved: true, }, "Linux-man-pages-copyleft": { - "name": "Linux man-pages Copyleft", - "url": "https://www.kernel.org/doc/man-pages/licenses.html", - "osiApproved": false + name: "Linux man-pages Copyleft", + url: "https://www.kernel.org/doc/man-pages/licenses.html", + osiApproved: false, }, "NTP-0": { - "name": "NTP No Attribution", - "url": "https://github.com/tytso/e2fsprogs/blob/master/lib/et/et_name.c", - "osiApproved": false + name: "NTP No Attribution", + url: "https://github.com/tytso/e2fsprogs/blob/master/lib/et/et_name.c", + osiApproved: false, }, - "curl": { - "name": "curl License", - "url": "https://github.com/bagder/curl/blob/master/COPYING", - "osiApproved": false + curl: { + name: "curl License", + url: "https://github.com/bagder/curl/blob/master/COPYING", + osiApproved: false, }, - "MITNFA": { - "name": "MIT +no-false-attribs license", - "url": "https://fedoraproject.org/wiki/Licensing/MITNFA", - "osiApproved": false + MITNFA: { + name: "MIT +no-false-attribs license", + url: "https://fedoraproject.org/wiki/Licensing/MITNFA", + osiApproved: false, }, - "libtiff": { - "name": "libtiff License", - "url": "https://fedoraproject.org/wiki/Licensing/libtiff", - "osiApproved": false + libtiff: { + name: "libtiff License", + url: "https://fedoraproject.org/wiki/Licensing/libtiff", + osiApproved: false, }, "ErlPL-1.1": { - "name": "Erlang Public License v1.1", - "url": "http://www.erlang.org/EPLICENSE", - "osiApproved": false + name: "Erlang Public License v1.1", + url: "http://www.erlang.org/EPLICENSE", + osiApproved: false, }, "Adobe-Utopia": { - "name": "Adobe Utopia Font License", - "url": "https://gitlab.freedesktop.org/xorg/font/adobe-utopia-100dpi/-/blob/master/COPYING?ref_type=heads", - "osiApproved": false + name: "Adobe Utopia Font License", + url: "https://gitlab.freedesktop.org/xorg/font/adobe-utopia-100dpi/-/blob/master/COPYING?ref_type=heads", + osiApproved: false, }, - "HaskellReport": { - "name": "Haskell Language Report License", - "url": "https://fedoraproject.org/wiki/Licensing/Haskell_Language_Report_License", - "osiApproved": false + HaskellReport: { + name: "Haskell Language Report License", + url: "https://fedoraproject.org/wiki/Licensing/Haskell_Language_Report_License", + osiApproved: false, }, - "ISC": { - "name": "ISC License", - "url": "https://www.isc.org/licenses/", - "osiApproved": true + ISC: { + name: "ISC License", + url: "https://www.isc.org/licenses/", + osiApproved: true, }, - "Naumen": { - "name": "Naumen Public License", - "url": "https://opensource.org/licenses/Naumen", - "osiApproved": true + Naumen: { + name: "Naumen Public License", + url: "https://opensource.org/licenses/Naumen", + osiApproved: true, }, "CC-BY-SA-1.0": { - "name": "Creative Commons Attribution Share Alike 1.0 Generic", - "url": "https://creativecommons.org/licenses/by-sa/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 1.0 Generic", + url: "https://creativecommons.org/licenses/by-sa/1.0/legalcode", + osiApproved: false, }, "etalab-2.0": { - "name": "Etalab Open License 2.0", - "url": "https://github.com/DISIC/politique-de-contribution-open-source/blob/master/LICENSE.pdf", - "osiApproved": false + name: "Etalab Open License 2.0", + url: "https://github.com/DISIC/politique-de-contribution-open-source/blob/master/LICENSE.pdf", + osiApproved: false, }, "MPEG-SSG": { - "name": "MPEG Software Simulation", - "url": "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/converter/ppm/ppmtompeg/jrevdct.c#l1189", - "osiApproved": false + name: "MPEG Software Simulation", + url: "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/converter/ppm/ppmtompeg/jrevdct.c#l1189", + osiApproved: false, }, - "CFITSIO": { - "name": "CFITSIO License", - "url": "https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/f_user/node9.html", - "osiApproved": false + CFITSIO: { + name: "CFITSIO License", + url: "https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/f_user/node9.html", + osiApproved: false, }, "MulanPSL-1.0": { - "name": "Mulan Permissive Software License, Version 1", - "url": "https://license.coscl.org.cn/MulanPSL/", - "osiApproved": false + name: "Mulan Permissive Software License, Version 1", + url: "https://license.coscl.org.cn/MulanPSL/", + osiApproved: false, }, "GPL-2.0+": { - "name": "GNU General Public License v2.0 or later", - "url": "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v2.0 or later", + url: "https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html", + osiApproved: true, }, "BSD-2-Clause-Patent": { - "name": "BSD-2-Clause Plus Patent License", - "url": "https://opensource.org/licenses/BSDplusPatent", - "osiApproved": true + name: "BSD-2-Clause Plus Patent License", + url: "https://opensource.org/licenses/BSDplusPatent", + osiApproved: true, }, "CC-PDDC": { - "name": "Creative Commons Public Domain Dedication and Certification", - "url": "https://creativecommons.org/licenses/publicdomain/", - "osiApproved": false + name: "Creative Commons Public Domain Dedication and Certification", + url: "https://creativecommons.org/licenses/publicdomain/", + osiApproved: false, }, "TGPPL-1.0": { - "name": "Transitive Grace Period Public Licence 1.0", - "url": "https://fedoraproject.org/wiki/Licensing/TGPPL", - "osiApproved": false + name: "Transitive Grace Period Public Licence 1.0", + url: "https://fedoraproject.org/wiki/Licensing/TGPPL", + osiApproved: false, }, - "snprintf": { - "name": "snprintf License", - "url": "https://github.com/openssh/openssh-portable/blob/master/openbsd-compat/bsd-snprintf.c#L2", - "osiApproved": false + snprintf: { + name: "snprintf License", + url: "https://github.com/openssh/openssh-portable/blob/master/openbsd-compat/bsd-snprintf.c#L2", + osiApproved: false, }, - "Nunit": { - "name": "Nunit License", - "url": "https://fedoraproject.org/wiki/Licensing/Nunit", - "osiApproved": false + Nunit: { + name: "Nunit License", + url: "https://fedoraproject.org/wiki/Licensing/Nunit", + osiApproved: false, }, "Boehm-GC-without-fee": { - "name": "Boehm-Demers-Weiser GC License (without fee)", - "url": "https://github.com/MariaDB/server/blob/11.6/libmysqld/lib_sql.cc", - "osiApproved": false + name: "Boehm-Demers-Weiser GC License (without fee)", + url: "https://github.com/MariaDB/server/blob/11.6/libmysqld/lib_sql.cc", + osiApproved: false, }, - "Pixar": { - "name": "Pixar License", - "url": "https://github.com/PixarAnimationStudios/OpenSubdiv/raw/v3_5_0/LICENSE.txt", - "osiApproved": false + Pixar: { + name: "Pixar License", + url: "https://github.com/PixarAnimationStudios/OpenSubdiv/raw/v3_5_0/LICENSE.txt", + osiApproved: false, }, "HPND-Netrek": { - "name": "Historical Permission Notice and Disclaimer - Netrek variant", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - Netrek variant", + osiApproved: false, }, - "Minpack": { - "name": "Minpack License", - "url": "http://www.netlib.org/minpack/disclaimer", - "osiApproved": false + Minpack: { + name: "Minpack License", + url: "http://www.netlib.org/minpack/disclaimer", + osiApproved: false, }, "GFDL-1.1-only": { - "name": "GNU Free Documentation License v1.1 only", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1 only", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, "HPND-INRIA-IMAG": { - "name": "Historical Permission Notice and Disclaimer - INRIA-IMAG variant", - "url": "https://github.com/ppp-project/ppp/blob/master/pppd/ipv6cp.c#L75-L83", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - INRIA-IMAG variant", + url: "https://github.com/ppp-project/ppp/blob/master/pppd/ipv6cp.c#L75-L83", + osiApproved: false, }, "App-s2p": { - "name": "App::s2p License", - "url": "https://fedoraproject.org/wiki/Licensing/App-s2p", - "osiApproved": false + name: "App::s2p License", + url: "https://fedoraproject.org/wiki/Licensing/App-s2p", + osiApproved: false, }, "BSD-3-Clause-acpica": { - "name": "BSD 3-Clause acpica variant", - "url": "https://github.com/acpica/acpica/blob/master/source/common/acfileio.c#L119", - "osiApproved": false + name: "BSD 3-Clause acpica variant", + url: "https://github.com/acpica/acpica/blob/master/source/common/acfileio.c#L119", + osiApproved: false, }, - "OGTSL": { - "name": "Open Group Test Suite License", - "url": "http://www.opengroup.org/testing/downloads/The_Open_Group_TSL.txt", - "osiApproved": true + OGTSL: { + name: "Open Group Test Suite License", + url: "http://www.opengroup.org/testing/downloads/The_Open_Group_TSL.txt", + osiApproved: true, }, "ODbL-1.0": { - "name": "Open Data Commons Open Database License v1.0", - "url": "http://www.opendatacommons.org/licenses/odbl/1.0/", - "osiApproved": false + name: "Open Data Commons Open Database License v1.0", + url: "http://www.opendatacommons.org/licenses/odbl/1.0/", + osiApproved: false, }, "CC-BY-ND-3.0": { - "name": "Creative Commons Attribution No Derivatives 3.0 Unported", - "url": "https://creativecommons.org/licenses/by-nd/3.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution No Derivatives 3.0 Unported", + url: "https://creativecommons.org/licenses/by-nd/3.0/legalcode", + osiApproved: false, }, "CC-BY-SA-2.5": { - "name": "Creative Commons Attribution Share Alike 2.5 Generic", - "url": "https://creativecommons.org/licenses/by-sa/2.5/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Share Alike 2.5 Generic", + url: "https://creativecommons.org/licenses/by-sa/2.5/legalcode", + osiApproved: false, }, "OLDAP-2.7": { - "name": "Open LDAP Public License v2.7", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=47c2415c1df81556eeb39be6cad458ef87c534a2", - "osiApproved": false + name: "Open LDAP Public License v2.7", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=47c2415c1df81556eeb39be6cad458ef87c534a2", + osiApproved: false, }, "UCL-1.0": { - "name": "Upstream Compatibility License v1.0", - "url": "https://opensource.org/licenses/UCL-1.0", - "osiApproved": true + name: "Upstream Compatibility License v1.0", + url: "https://opensource.org/licenses/UCL-1.0", + osiApproved: true, }, - "MTLL": { - "name": "Matrix Template Library License", - "url": "https://fedoraproject.org/wiki/Licensing/Matrix_Template_Library_License", - "osiApproved": false + MTLL: { + name: "Matrix Template Library License", + url: "https://fedoraproject.org/wiki/Licensing/Matrix_Template_Library_License", + osiApproved: false, }, "HPND-export2-US": { - "name": "HPND with US Government export control and 2 disclaimers", - "url": "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L111-L133", - "osiApproved": false + name: "HPND with US Government export control and 2 disclaimers", + url: "https://github.com/krb5/krb5/blob/krb5-1.21.2-final/NOTICE#L111-L133", + osiApproved: false, }, "OFL-1.0-RFN": { - "name": "SIL Open Font License 1.0 with Reserved Font Name", - "url": "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL10_web", - "osiApproved": false + name: "SIL Open Font License 1.0 with Reserved Font Name", + url: "http://scripts.sil.org/cms/scripts/page.php?item_id=OFL10_web", + osiApproved: false, }, "ZPL-2.0": { - "name": "Zope Public License 2.0", - "url": "http://old.zope.org/Resources/License/ZPL-2.0", - "osiApproved": true + name: "Zope Public License 2.0", + url: "http://old.zope.org/Resources/License/ZPL-2.0", + osiApproved: true, }, "bcrypt-Solar-Designer": { - "name": "bcrypt Solar Designer License", - "url": "https://github.com/bcrypt-ruby/bcrypt-ruby/blob/master/ext/mri/crypt_blowfish.c", - "osiApproved": false + name: "bcrypt Solar Designer License", + url: "https://github.com/bcrypt-ruby/bcrypt-ruby/blob/master/ext/mri/crypt_blowfish.c", + osiApproved: false, }, "CC-BY-NC-SA-3.0-DE": { - "name": "Creative Commons Attribution Non Commercial Share Alike 3.0 Germany", - "url": "https://creativecommons.org/licenses/by-nc-sa/3.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 3.0 Germany", + url: "https://creativecommons.org/licenses/by-nc-sa/3.0/de/legalcode", + osiApproved: false, }, "GFDL-1.1-no-invariants-or-later": { - "name": "GNU Free Documentation License v1.1 or later - no invariants", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.1 or later - no invariants", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.1.txt", + osiApproved: false, }, "CC-BY-SA-3.0-IGO": { - "name": "Creative Commons Attribution-ShareAlike 3.0 IGO", - "url": "https://creativecommons.org/licenses/by-sa/3.0/igo/legalcode", - "osiApproved": false + name: "Creative Commons Attribution-ShareAlike 3.0 IGO", + url: "https://creativecommons.org/licenses/by-sa/3.0/igo/legalcode", + osiApproved: false, }, "Apache-1.1": { - "name": "Apache License 1.1", - "url": "http://apache.org/licenses/LICENSE-1.1", - "osiApproved": true + name: "Apache License 1.1", + url: "http://apache.org/licenses/LICENSE-1.1", + osiApproved: true, }, "GPL-2.0-with-autoconf-exception": { - "name": "GNU General Public License v2.0 w/Autoconf exception", - "url": "http://ac-archive.sourceforge.net/doc/copyright.html", - "osiApproved": false + name: "GNU General Public License v2.0 w/Autoconf exception", + url: "http://ac-archive.sourceforge.net/doc/copyright.html", + osiApproved: false, }, "Caldera-no-preamble": { - "name": "Caldera License (without preamble)", - "url": "https://github.com/apache/apr/blob/trunk/LICENSE#L298C6-L298C29", - "osiApproved": false + name: "Caldera License (without preamble)", + url: "https://github.com/apache/apr/blob/trunk/LICENSE#L298C6-L298C29", + osiApproved: false, }, "SSPL-1.0": { - "name": "Server Side Public License, v 1", - "url": "https://www.mongodb.com/licensing/server-side-public-license", - "osiApproved": false + name: "Server Side Public License, v 1", + url: "https://www.mongodb.com/licensing/server-side-public-license", + osiApproved: false, }, "DRL-1.1": { - "name": "Detection Rule License 1.1", - "url": "https://github.com/SigmaHQ/Detection-Rule-License/blob/6ec7fbde6101d101b5b5d1fcb8f9b69fbc76c04a/LICENSE.Detection.Rules.md", - "osiApproved": false + name: "Detection Rule License 1.1", + url: "https://github.com/SigmaHQ/Detection-Rule-License/blob/6ec7fbde6101d101b5b5d1fcb8f9b69fbc76c04a/LICENSE.Detection.Rules.md", + osiApproved: false, }, "Linux-man-pages-copyleft-2-para": { - "name": "Linux man-pages Copyleft - 2 paragraphs", - "url": "https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/move_pages.2#n5", - "osiApproved": false + name: "Linux man-pages Copyleft - 2 paragraphs", + url: "https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man2/move_pages.2#n5", + osiApproved: false, }, "OLDAP-2.0.1": { - "name": "Open LDAP Public License v2.0.1", - "url": "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=b6d68acd14e51ca3aab4428bf26522aa74873f0e", - "osiApproved": false + name: "Open LDAP Public License v2.0.1", + url: "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=blob;f=LICENSE;hb=b6d68acd14e51ca3aab4428bf26522aa74873f0e", + osiApproved: false, }, "ANTLR-PD-fallback": { - "name": "ANTLR Software Rights Notice with license fallback", - "url": "http://www.antlr2.org/license.html", - "osiApproved": false + name: "ANTLR Software Rights Notice with license fallback", + url: "http://www.antlr2.org/license.html", + osiApproved: false, }, "CDLA-Permissive-2.0": { - "name": "Community Data License Agreement Permissive 2.0", - "url": "https://cdla.dev/permissive-2-0", - "osiApproved": false + name: "Community Data License Agreement Permissive 2.0", + url: "https://cdla.dev/permissive-2-0", + osiApproved: false, }, - "HIDAPI": { - "name": "HIDAPI License", - "url": "https://github.com/signal11/hidapi/blob/master/LICENSE-orig.txt", - "osiApproved": false + HIDAPI: { + name: "HIDAPI License", + url: "https://github.com/signal11/hidapi/blob/master/LICENSE-orig.txt", + osiApproved: false, }, "bzip2-1.0.6": { - "name": "bzip2 and libbzip2 License v1.0.6", - "url": "https://sourceware.org/git/?p=bzip2.git;a=blob;f=LICENSE;hb=bzip2-1.0.6", - "osiApproved": false + name: "bzip2 and libbzip2 License v1.0.6", + url: "https://sourceware.org/git/?p=bzip2.git;a=blob;f=LICENSE;hb=bzip2-1.0.6", + osiApproved: false, }, - "GL2PS": { - "name": "GL2PS License", - "url": "http://www.geuz.org/gl2ps/COPYING.GL2PS", - "osiApproved": false + GL2PS: { + name: "GL2PS License", + url: "http://www.geuz.org/gl2ps/COPYING.GL2PS", + osiApproved: false, }, - "TOSL": { - "name": "Trusster Open Source License", - "url": "https://fedoraproject.org/wiki/Licensing/TOSL", - "osiApproved": false + TOSL: { + name: "Trusster Open Source License", + url: "https://fedoraproject.org/wiki/Licensing/TOSL", + osiApproved: false, }, - "Abstyles": { - "name": "Abstyles License", - "url": "https://fedoraproject.org/wiki/Licensing/Abstyles", - "osiApproved": false + Abstyles: { + name: "Abstyles License", + url: "https://fedoraproject.org/wiki/Licensing/Abstyles", + osiApproved: false, }, - "TermReadKey": { - "name": "TermReadKey License", - "url": "https://github.com/jonathanstowe/TermReadKey/blob/master/README#L9-L10", - "osiApproved": false + TermReadKey: { + name: "TermReadKey License", + url: "https://github.com/jonathanstowe/TermReadKey/blob/master/README#L9-L10", + osiApproved: false, }, "GFDL-1.2": { - "name": "GNU Free Documentation License v1.2", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, - "xzoom": { - "name": "xzoom License", - "url": "https://metadata.ftp-master.debian.org/changelogs//main/x/xzoom/xzoom_0.3-27_copyright", - "osiApproved": false + xzoom: { + name: "xzoom License", + url: "https://metadata.ftp-master.debian.org/changelogs//main/x/xzoom/xzoom_0.3-27_copyright", + osiApproved: false, }, - "PostgreSQL": { - "name": "PostgreSQL License", - "url": "http://www.postgresql.org/about/licence", - "osiApproved": true + PostgreSQL: { + name: "PostgreSQL License", + url: "http://www.postgresql.org/about/licence", + osiApproved: true, }, "CNRI-Python-GPL-Compatible": { - "name": "CNRI Python Open Source GPL Compatible License Agreement", - "url": "http://www.python.org/download/releases/1.6.1/download_win/", - "osiApproved": false + name: "CNRI Python Open Source GPL Compatible License Agreement", + url: "http://www.python.org/download/releases/1.6.1/download_win/", + osiApproved: false, }, "Widget-Workshop": { - "name": "Widget Workshop License", - "url": "https://github.com/novnc/noVNC/blob/master/core/crypto/des.js#L24", - "osiApproved": false + name: "Widget Workshop License", + url: "https://github.com/novnc/noVNC/blob/master/core/crypto/des.js#L24", + osiApproved: false, }, - "Libpng": { - "name": "libpng License", - "url": "http://www.libpng.org/pub/png/src/libpng-LICENSE.txt", - "osiApproved": false + Libpng: { + name: "libpng License", + url: "http://www.libpng.org/pub/png/src/libpng-LICENSE.txt", + osiApproved: false, }, "HPND-sell-MIT-disclaimer-xserver": { - "name": "Historical Permission Notice and Disclaimer - sell xserver variant with MIT disclaimer", - "url": "https://gitlab.freedesktop.org/xorg/xserver/-/blob/master/COPYING?ref_type=heads#L1781", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - sell xserver variant with MIT disclaimer", + url: "https://gitlab.freedesktop.org/xorg/xserver/-/blob/master/COPYING?ref_type=heads#L1781", + osiApproved: false, }, "CC-BY-NC-SA-1.0": { - "name": "Creative Commons Attribution Non Commercial Share Alike 1.0 Generic", - "url": "https://creativecommons.org/licenses/by-nc-sa/1.0/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial Share Alike 1.0 Generic", + url: "https://creativecommons.org/licenses/by-nc-sa/1.0/legalcode", + osiApproved: false, }, "Python-2.0": { - "name": "Python License 2.0", - "url": "https://opensource.org/licenses/Python-2.0", - "osiApproved": true + name: "Python License 2.0", + url: "https://opensource.org/licenses/Python-2.0", + osiApproved: true, }, "BSD-Systemics-W3Works": { - "name": "Systemics W3Works BSD variant license", - "url": "https://metacpan.org/release/DPARIS/Crypt-Blowfish-2.14/source/COPYRIGHT#L7", - "osiApproved": false + name: "Systemics W3Works BSD variant license", + url: "https://metacpan.org/release/DPARIS/Crypt-Blowfish-2.14/source/COPYRIGHT#L7", + osiApproved: false, }, "LPPL-1.0": { - "name": "LaTeX Project Public License v1.0", - "url": "http://www.latex-project.org/lppl/lppl-1-0.txt", - "osiApproved": false + name: "LaTeX Project Public License v1.0", + url: "http://www.latex-project.org/lppl/lppl-1-0.txt", + osiApproved: false, }, "YPL-1.1": { - "name": "Yahoo! Public License v1.1", - "url": "http://www.zimbra.com/license/yahoo_public_license_1.1.html", - "osiApproved": false + name: "Yahoo! Public License v1.1", + url: "http://www.zimbra.com/license/yahoo_public_license_1.1.html", + osiApproved: false, }, - "SWL": { - "name": "Scheme Widget Library (SWL) Software License Agreement", - "url": "https://fedoraproject.org/wiki/Licensing/SWL", - "osiApproved": false + SWL: { + name: "Scheme Widget Library (SWL) Software License Agreement", + url: "https://fedoraproject.org/wiki/Licensing/SWL", + osiApproved: false, }, - "Giftware": { - "name": "Giftware License", - "url": "http://liballeg.org/license.html#allegro-4-the-giftware-license", - "osiApproved": false + Giftware: { + name: "Giftware License", + url: "http://liballeg.org/license.html#allegro-4-the-giftware-license", + osiApproved: false, }, "CECILL-B": { - "name": "CeCILL-B Free Software License Agreement", - "url": "http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html", - "osiApproved": false + name: "CeCILL-B Free Software License Agreement", + url: "http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html", + osiApproved: false, }, "OSET-PL-2.1": { - "name": "OSET Public License version 2.1", - "url": "http://www.osetfoundation.org/public-license", - "osiApproved": true + name: "OSET Public License version 2.1", + url: "http://www.osetfoundation.org/public-license", + osiApproved: true, }, "GPL-3.0-with-autoconf-exception": { - "name": "GNU General Public License v3.0 w/Autoconf exception", - "url": "https://www.gnu.org/licenses/autoconf-exception-3.0.html", - "osiApproved": false + name: "GNU General Public License v3.0 w/Autoconf exception", + url: "https://www.gnu.org/licenses/autoconf-exception-3.0.html", + osiApproved: false, }, "CAL-1.0-Combined-Work-Exception": { - "name": "Cryptographic Autonomy License 1.0 (Combined Work Exception)", - "url": "http://cryptographicautonomylicense.com/license-text.html", - "osiApproved": true + name: "Cryptographic Autonomy License 1.0 (Combined Work Exception)", + url: "http://cryptographicautonomylicense.com/license-text.html", + osiApproved: true, }, "HPND-sell-variant-MIT-disclaimer-rev": { - "name": "HPND sell variant with MIT disclaimer - reverse", - "url": "https://github.com/sigmavirus24/x11-ssh-askpass/blob/master/dynlist.c", - "osiApproved": false + name: "HPND sell variant with MIT disclaimer - reverse", + url: "https://github.com/sigmavirus24/x11-ssh-askpass/blob/master/dynlist.c", + osiApproved: false, }, - "JSON": { - "name": "JSON License", - "url": "http://www.json.org/license.html", - "osiApproved": false + JSON: { + name: "JSON License", + url: "http://www.json.org/license.html", + osiApproved: false, }, "GFDL-1.2-only": { - "name": "GNU Free Documentation License v1.2 only", - "url": "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", - "osiApproved": false + name: "GNU Free Documentation License v1.2 only", + url: "https://www.gnu.org/licenses/old-licenses/fdl-1.2.txt", + osiApproved: false, }, - "pkgconf": { - "name": "pkgconf License", - "url": "https://github.com/pkgconf/pkgconf/blob/master/cli/main.c#L8", - "osiApproved": false + pkgconf: { + name: "pkgconf License", + url: "https://github.com/pkgconf/pkgconf/blob/master/cli/main.c#L8", + osiApproved: false, }, "Unicode-DFS-2016": { - "name": "Unicode License Agreement - Data Files and Software (2016)", - "url": "https://www.unicode.org/license.txt", - "osiApproved": true + name: "Unicode License Agreement - Data Files and Software (2016)", + url: "https://www.unicode.org/license.txt", + osiApproved: true, }, "PHP-3.01": { - "name": "PHP License v3.01", - "url": "http://www.php.net/license/3_01.txt", - "osiApproved": true + name: "PHP License v3.01", + url: "http://www.php.net/license/3_01.txt", + osiApproved: true, }, - "blessing": { - "name": "SQLite Blessing", - "url": "https://www.sqlite.org/src/artifact/e33a4df7e32d742a?ln=4-9", - "osiApproved": false + blessing: { + name: "SQLite Blessing", + url: "https://www.sqlite.org/src/artifact/e33a4df7e32d742a?ln=4-9", + osiApproved: false, }, "RPSL-1.0": { - "name": "RealNetworks Public Source License v1.0", - "url": "https://helixcommunity.org/content/rpsl", - "osiApproved": true + name: "RealNetworks Public Source License v1.0", + url: "https://helixcommunity.org/content/rpsl", + osiApproved: true, }, "BitTorrent-1.0": { - "name": "BitTorrent Open Source License v1.0", - "url": "http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/licenses/BitTorrent?r1=1.1&r2=1.1.1.1&diff_format=s", - "osiApproved": false + name: "BitTorrent Open Source License v1.0", + url: "http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/licenses/BitTorrent?r1=1.1&r2=1.1.1.1&diff_format=s", + osiApproved: false, }, "SISSL-1.2": { - "name": "Sun Industry Standards Source License v1.2", - "url": "http://gridscheduler.sourceforge.net/Gridengine_SISSL_license.html", - "osiApproved": false + name: "Sun Industry Standards Source License v1.2", + url: "http://gridscheduler.sourceforge.net/Gridengine_SISSL_license.html", + osiApproved: false, }, "GPL-3.0": { - "name": "GNU General Public License v3.0 only", - "url": "https://www.gnu.org/licenses/gpl-3.0-standalone.html", - "osiApproved": true + name: "GNU General Public License v3.0 only", + url: "https://www.gnu.org/licenses/gpl-3.0-standalone.html", + osiApproved: true, }, - "IJG": { - "name": "Independent JPEG Group License", - "url": "http://dev.w3.org/cvsweb/Amaya/libjpeg/Attic/README?rev=1.2", - "osiApproved": false + IJG: { + name: "Independent JPEG Group License", + url: "http://dev.w3.org/cvsweb/Amaya/libjpeg/Attic/README?rev=1.2", + osiApproved: false, }, "OGL-Canada-2.0": { - "name": "Open Government Licence - Canada", - "url": "https://open.canada.ca/en/open-government-licence-canada", - "osiApproved": false + name: "Open Government Licence - Canada", + url: "https://open.canada.ca/en/open-government-licence-canada", + osiApproved: false, }, "CC-BY-ND-2.5": { - "name": "Creative Commons Attribution No Derivatives 2.5 Generic", - "url": "https://creativecommons.org/licenses/by-nd/2.5/legalcode", - "osiApproved": false + name: "Creative Commons Attribution No Derivatives 2.5 Generic", + url: "https://creativecommons.org/licenses/by-nd/2.5/legalcode", + osiApproved: false, }, "HPND-Pbmplus": { - "name": "Historical Permission Notice and Disclaimer - Pbmplus variant", - "url": "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/netpbm.c#l8", - "osiApproved": false + name: "Historical Permission Notice and Disclaimer - Pbmplus variant", + url: "https://sourceforge.net/p/netpbm/code/HEAD/tree/super_stable/netpbm.c#l8", + osiApproved: false, }, "CC-BY-NC-ND-3.0-DE": { - "name": "Creative Commons Attribution Non Commercial No Derivatives 3.0 Germany", - "url": "https://creativecommons.org/licenses/by-nc-nd/3.0/de/legalcode", - "osiApproved": false + name: "Creative Commons Attribution Non Commercial No Derivatives 3.0 Germany", + url: "https://creativecommons.org/licenses/by-nc-nd/3.0/de/legalcode", + osiApproved: false, }, "RPL-1.5": { - "name": "Reciprocal Public License 1.5", - "url": "https://opensource.org/licenses/RPL-1.5", - "osiApproved": true + name: "Reciprocal Public License 1.5", + url: "https://opensource.org/licenses/RPL-1.5", + osiApproved: true, }, - "Nokia": { - "name": "Nokia Open Source License", - "url": "https://opensource.org/licenses/nokia", - "osiApproved": true + Nokia: { + name: "Nokia Open Source License", + url: "https://opensource.org/licenses/nokia", + osiApproved: true, }, "HPND-doc-sell": { - "name": "Historical Permission Notice and Disclaimer - documentation sell variant", - "url": "https://gitlab.freedesktop.org/xorg/lib/libxtst/-/blob/master/COPYING?ref_type=heads#L108-117", - "osiApproved": false - } -} as const \ No newline at end of file + name: "Historical Permission Notice and Disclaimer - documentation sell variant", + url: "https://gitlab.freedesktop.org/xorg/lib/libxtst/-/blob/master/COPYING?ref_type=heads#L108-117", + osiApproved: false, + }, +} as const; diff --git a/biome.json b/biome.json new file mode 100644 index 0000000..b46c327 --- /dev/null +++ b/biome.json @@ -0,0 +1,22 @@ +{ + "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", + "vcs": { + "enabled": true, + "clientKind": "git", + "defaultBranch": "main", + "useIgnoreFile": true + }, + "formatter": { + "enabled": true + }, + "linter": { + "enabled": true, + "rules": { + "recommended": true, + "correctness": { + "noUnusedVariables": "error", + "noUnusedFunctionParameters": "warn" + } + } + } +} diff --git a/bunfig.toml b/bunfig.toml index 101a497..921095b 100644 --- a/bunfig.toml +++ b/bunfig.toml @@ -1,7 +1,3 @@ -[test] -# Bun test configuration -preload = ["./tests/setup.ts"] - [install] # Install configuration cache = true diff --git a/index.ts b/index.ts index c05a05b..47b6748 100644 --- a/index.ts +++ b/index.ts @@ -3,34 +3,33 @@ * @fileoverview Main entry point for OpenAPI type definitions * @version 1.0.0 * @since 2024-12-19 - * + * * This library provides comprehensive TypeScript definitions for all OpenAPI specification versions: * - Swagger 2.0 (OpenAPI Specification v2.0) * - OpenAPI 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4 * - OpenAPI 3.1.0, 3.1.1 - * + * - OpenAPI 3.2.0 + * * The library is organized with atomic building blocks (atoms/) that are shared across versions, * and version-specific implementations that extend or override these atoms as needed. - * + * * ## Import Paths - * + * * For the best developer experience, use these import paths: - * - `oas-types/atoms` - Atomic building blocks - * - `oas-types/utils` - Utility types - * - `oas-types/common` - Common types and enums - * - `oas-types/3.1.0` - OpenAPI 3.1.0 types - * - `oas-types/3.0.0` - OpenAPI 3.0.0 types - * - `oas-types/2.0` - Swagger 2.0 types - * + * - `oas-types/3.1.x` - OpenAPI 3.1.x types (latest) + * - `oas-types/3.0.x` - OpenAPI 3.0.x types + * - `oas-types/2.0.0` - Swagger 2.0 types + * - `oas-types/3.2.0` - OpenAPI 3.2.0 types + * * @see {@link https://swagger.io/specification/v2/ Swagger 2.0 Specification} * @see {@link https://spec.openapis.org/oas/v3.0.0 OpenAPI 3.0.0 Specification} * @see {@link https://spec.openapis.org/oas/v3.1.0 OpenAPI 3.1.0 Specification} * @see {@link https://spec.openapis.org/oas/v3.1.1 OpenAPI 3.1.1 Specification} + * @see {@link https://spec.openapis.org/oas/v3.2.0 OpenAPI 3.2.0 Specification} */ // Version-specific exports -export * as OpenAPI2 from './2.0.0'; -export * as OpenAPI3 from './3.0.x'; -export * as OpenAPI3_1 from './3.1.x'; -// export * as OpenAPI3_2 from './3.2.x'; - +export * as OpenAPI2 from "./2.0"; +export * as OpenAPI3 from "./3.0"; +export * as OpenAPI3_1 from "./3.1"; +export * as OpenAPI3_2 from "./3.2"; diff --git a/package.json b/package.json index 69c4b45..03ae764 100644 --- a/package.json +++ b/package.json @@ -1,116 +1,100 @@ { - "name": "oas-types", - "version": "1.0.0", - "description": "Comprehensive TypeScript definitions for all OpenAPI specification versions (Swagger 2.0, OpenAPI 3.0.0, 3.1.0, 3.1.1)", - "main": "index.ts", - "module": "index.ts", - "type": "module", - "types": "index.ts", - "exports": { - ".": { - "types": "./index.ts", - "import": "./index.ts" - }, - "./atoms": { - "types": "./src/atoms/index.ts", - "import": "./src/atoms/index.ts" - }, - "./utils": { - "types": "./src/utils/index.ts", - "import": "./src/utils/index.ts" - }, - "./common": { - "types": "./src/common.ts", - "import": "./src/common.ts" - }, - "./2.0": { - "types": "./src/swagger-2.0/index.ts", - "import": "./src/swagger-2.0/index.ts" - }, - "./3.0.0": { - "types": "./src/3.0.0/index.ts", - "import": "./src/3.0.0/index.ts" - }, - "./3.0.1": { - "types": "./src/3.0.1/index.ts", - "import": "./src/3.0.1/index.ts" - }, - "./3.0.2": { - "types": "./src/3.0.2/index.ts", - "import": "./src/3.0.2/index.ts" - }, - "./3.0.3": { - "types": "./src/3.0.3/index.ts", - "import": "./src/3.0.3/index.ts" - }, - "./3.0.4": { - "types": "./src/3.0.4/index.ts", - "import": "./src/3.0.4/index.ts" - }, - "./3.1.0": { - "types": "./src/3.1.0/index.ts", - "import": "./src/3.1.0/index.ts" - }, - "./3.1.1": { - "types": "./src/3.1.1/index.ts", - "import": "./src/3.1.1/index.ts" - }, - }, - "files": [ - "src/", - "index.ts", - "README.md", - "LICENSE" - ], - "keywords": [ - "openapi", - "swagger", - "typescript", - "types", - "definitions", - "api", - "specification", - "swagger-2.0", - "openapi-3.0.0", - "openapi-3.1.0", - "openapi-3.1.1", - "json-schema", - "rest", - "api-documentation" - ], - "author": "OpenAPI Types Contributors", - "license": "MIT", - "repository": { - "type": "git", - "url": "https://github.com/your-username/openapi-types.git" - }, - "bugs": { - "url": "https://github.com/your-username/openapi-types/issues" - }, - "homepage": "https://github.com/your-username/openapi-types#readme", - "dependencies": { - "spdx-license-list": "^6.10.0" - }, - "devDependencies": { - "@types/bun": "latest" - }, - "peerDependencies": { - "typescript": "^5.0.0" - }, - "engines": { - "node": ">=18.0.0" - }, - "scripts": { - "test": "bun test", - "test:watch": "bun test --watch", - "test:coverage": "bun test --coverage", - "test:common": "bun test tests/common.test.ts", - "test:open-enums": "bun test tests/open-enums.test.ts", - "test:swagger-2.0": "bun test tests/swagger-2.0.test.ts", - "test:openapi-3.0.0": "bun test tests/openapi-3.0.0.test.ts", - "test:integration": "bun test tests/integration.test.ts", - "type-check": "tsc --noEmit", - "build": "tsc", - "dev": "bun run --watch index.ts" - } + "name": "oas-types", + "version": "1.0.0", + "description": "Comprehensive TypeScript definitions for all OpenAPI specification versions (Swagger 2.0, OpenAPI 3.0.x, 3.1.x, 3.2.0)", + "main": "index.ts", + "module": "index.ts", + "type": "module", + "types": "index.ts", + "author": { + "name": "Luke Hagar", + "email": "lukeslakemail@gmail.com", + "url": "https://lukehagar.com/" + }, + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/lukehagar/openapi-types.git" + }, + "bugs": { + "url": "https://github.com/lukehagar/openapi-types/issues" + }, + "homepage": "https://github.com/lukehagar/openapi-types#readme", + "scripts": { + "test": "bun test", + "test:watch": "bun test --watch", + "test:coverage": "bun test --coverage", + "test:common": "bun test tests/common.test.ts", + "test:open-enums": "bun test tests/open-enums.test.ts", + "test:swagger-2.0": "bun test tests/swagger-2.0.test.ts", + "test:openapi-3.0.0": "bun test tests/openapi-3.0.0.test.ts", + "test:integration": "bun test tests/integration.test.ts", + "type-check": "tsc --noEmit", + "build": "tsc", + "dev": "bun run --watch index.ts", + "lint": "biome check .", + "lint:fix": "biome check --write ." + }, + "dependencies": { + "spdx-license-list": "^6.10.0" + }, + "devDependencies": { + "@biomejs/biome": "^2.2.4", + "@types/bun": "latest", + "tsd": "^0.33.0", + "typescript": "^5.9.2" + }, + "peerDependencies": { + "typescript": "^5.0.0" + }, + "exports": { + ".": { + "types": "./index.ts", + "import": "./index.ts" + }, + "./2.0": { + "types": "./2.0/index.ts", + "import": "./2.0/index.ts" + }, + "./3.0": { + "types": "./3.0/index.ts", + "import": "./3.0/index.ts" + }, + "./3.1": { + "types": "./3.1/index.ts", + "import": "./3.1/index.ts" + }, + "./3.2": { + "types": "./3.2/index.ts", + "import": "./3.2/index.ts" + } + }, + "files": [ + "2.0/", + "3.0/", + "3.1/", + "3.2/", + "License.ts", + "SPDXLicenseList.ts", + "MIGRATION.md", + "index.ts", + "README.md", + "LICENSE" + ], + "keywords": [ + "openapi", + "swagger", + "typescript", + "types", + "definitions", + "api", + "specification", + "swagger-2.0", + "openapi-3.0", + "openapi-3.1", + "openapi-3.2", + "json-schema", + "rest", + "api-documentation" + ] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml new file mode 100644 index 0000000..0e6a8aa --- /dev/null +++ b/pnpm-lock.yaml @@ -0,0 +1,1033 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + dependencies: + spdx-license-list: + specifier: ^6.10.0 + version: 6.10.0 + devDependencies: + '@biomejs/biome': + specifier: ^2.2.4 + version: 2.2.4 + '@types/bun': + specifier: latest + version: 1.2.22(@types/react@19.1.13) + tsd: + specifier: ^0.33.0 + version: 0.33.0 + typescript: + specifier: ^5.9.2 + version: 5.9.2 + +packages: + + '@babel/code-frame@7.27.1': + resolution: {integrity: sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==} + engines: {node: '>=6.9.0'} + + '@babel/helper-validator-identifier@7.27.1': + resolution: {integrity: sha512-D2hP9eA+Sqx1kBZgzxZh0y1trbuU+JoDkiEwqhQ36nodYqJwyEIhPSdMNd7lOm/4io72luTPWH20Yda0xOuUow==} + engines: {node: '>=6.9.0'} + + '@biomejs/biome@2.2.4': + resolution: {integrity: sha512-TBHU5bUy/Ok6m8c0y3pZiuO/BZoY/OcGxoLlrfQof5s8ISVwbVBdFINPQZyFfKwil8XibYWb7JMwnT8wT4WVPg==} + engines: {node: '>=14.21.3'} + hasBin: true + + '@biomejs/cli-darwin-arm64@2.2.4': + resolution: {integrity: sha512-RJe2uiyaloN4hne4d2+qVj3d3gFJFbmrr5PYtkkjei1O9c+BjGXgpUPVbi8Pl8syumhzJjFsSIYkcLt2VlVLMA==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [darwin] + + '@biomejs/cli-darwin-x64@2.2.4': + resolution: {integrity: sha512-cFsdB4ePanVWfTnPVaUX+yr8qV8ifxjBKMkZwN7gKb20qXPxd/PmwqUH8mY5wnM9+U0QwM76CxFyBRJhC9tQwg==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [darwin] + + '@biomejs/cli-linux-arm64-musl@2.2.4': + resolution: {integrity: sha512-7TNPkMQEWfjvJDaZRSkDCPT/2r5ESFPKx+TEev+I2BXDGIjfCZk2+b88FOhnJNHtksbOZv8ZWnxrA5gyTYhSsQ==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [linux] + + '@biomejs/cli-linux-arm64@2.2.4': + resolution: {integrity: sha512-M/Iz48p4NAzMXOuH+tsn5BvG/Jb07KOMTdSVwJpicmhN309BeEyRyQX+n1XDF0JVSlu28+hiTQ2L4rZPvu7nMw==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [linux] + + '@biomejs/cli-linux-x64-musl@2.2.4': + resolution: {integrity: sha512-m41nFDS0ksXK2gwXL6W6yZTYPMH0LughqbsxInSKetoH6morVj43szqKx79Iudkp8WRT5SxSh7qVb8KCUiewGg==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [linux] + + '@biomejs/cli-linux-x64@2.2.4': + resolution: {integrity: sha512-orr3nnf2Dpb2ssl6aihQtvcKtLySLta4E2UcXdp7+RTa7mfJjBgIsbS0B9GC8gVu0hjOu021aU8b3/I1tn+pVQ==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [linux] + + '@biomejs/cli-win32-arm64@2.2.4': + resolution: {integrity: sha512-NXnfTeKHDFUWfxAefa57DiGmu9VyKi0cDqFpdI+1hJWQjGJhJutHPX0b5m+eXvTKOaf+brU+P0JrQAZMb5yYaQ==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [win32] + + '@biomejs/cli-win32-x64@2.2.4': + resolution: {integrity: sha512-3Y4V4zVRarVh/B/eSHczR4LYoSVyv3Dfuvm3cWs5w/HScccS0+Wt/lHOcDTRYeHjQmMYVC3rIRWqyN2EI52+zg==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [win32] + + '@jest/schemas@29.6.3': + resolution: {integrity: sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA==} + engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} + + '@nodelib/fs.scandir@2.1.5': + resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==} + engines: {node: '>= 8'} + + '@nodelib/fs.stat@2.0.5': + resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==} + engines: {node: '>= 8'} + + '@nodelib/fs.walk@1.2.8': + resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==} + engines: {node: '>= 8'} + + '@sinclair/typebox@0.27.8': + resolution: {integrity: sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==} + + '@tsd/typescript@5.9.2': + resolution: {integrity: sha512-mSMM0QtEPdMd+rdMDd17yCUYD4yI3pKHap89+jEZrZ3KIO5PhDofBjER0OtgHdvOXF74KMLO3fyD6k3Hz0v03A==} + engines: {node: '>=14.17'} + + '@types/bun@1.2.22': + resolution: {integrity: sha512-5A/KrKos2ZcN0c6ljRSOa1fYIyCKhZfIVYeuyb4snnvomnpFqC0tTsEkdqNxbAgExV384OETQ//WAjl3XbYqQA==} + + '@types/eslint@7.29.0': + resolution: {integrity: sha512-VNcvioYDH8/FxaeTKkM4/TiTwt6pBV9E3OfGmvaw8tPl0rrHCJ4Ll15HRT+pMiFAf/MLQvAzC+6RzUMEL9Ceng==} + + '@types/estree@1.0.8': + resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==} + + '@types/json-schema@7.0.15': + resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} + + '@types/minimist@1.2.5': + resolution: {integrity: sha512-hov8bUuiLiyFPGyFPE1lwWhmzYbirOXQNNo40+y3zow8aFVTeyn3VWL0VFFfdNddA8S4Vf0Tc062rzyNr7Paag==} + + '@types/node@24.5.2': + resolution: {integrity: sha512-FYxk1I7wPv3K2XBaoyH2cTnocQEu8AOZ60hPbsyukMPLv5/5qr7V1i8PLHdl6Zf87I+xZXFvPCXYjiTFq+YSDQ==} + + '@types/normalize-package-data@2.4.4': + resolution: {integrity: sha512-37i+OaWTh9qeK4LSHPsyRC7NahnGotNuZvjLSgcPzblpHB3rrCJxAOgI5gCdKm7coonsaX1Of0ILiTcnZjbfxA==} + + '@types/react@19.1.13': + resolution: {integrity: sha512-hHkbU/eoO3EG5/MZkuFSKmYqPbSVk5byPFa3e7y/8TybHiLMACgI8seVYlicwk7H5K/rI2px9xrQp/C+AUDTiQ==} + + ansi-escapes@4.3.2: + resolution: {integrity: sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ==} + engines: {node: '>=8'} + + ansi-regex@5.0.1: + resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==} + engines: {node: '>=8'} + + ansi-styles@4.3.0: + resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==} + engines: {node: '>=8'} + + ansi-styles@5.2.0: + resolution: {integrity: sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==} + engines: {node: '>=10'} + + array-union@2.1.0: + resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==} + engines: {node: '>=8'} + + arrify@1.0.1: + resolution: {integrity: sha512-3CYzex9M9FGQjCGMGyi6/31c8GJbgb0qGyrx5HWxPd0aCwh4cB2YjMb2Xf9UuoogrMrlO9cTqnB5rI5GHZTcUA==} + engines: {node: '>=0.10.0'} + + braces@3.0.3: + resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==} + engines: {node: '>=8'} + + bun-types@1.2.22: + resolution: {integrity: sha512-hwaAu8tct/Zn6Zft4U9BsZcXkYomzpHJX28ofvx7k0Zz2HNz54n1n+tDgxoWFGB4PcFvJXJQloPhaV2eP3Q6EA==} + peerDependencies: + '@types/react': ^19 + + camelcase-keys@6.2.2: + resolution: {integrity: sha512-YrwaA0vEKazPBkn0ipTiMpSajYDSe+KjQfrjhcBMxJt/znbvlHd8Pw/Vamaz5EB4Wfhs3SUR3Z9mwRu/P3s3Yg==} + engines: {node: '>=8'} + + camelcase@5.3.1: + resolution: {integrity: sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==} + engines: {node: '>=6'} + + chalk@4.1.2: + resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==} + engines: {node: '>=10'} + + color-convert@2.0.1: + resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==} + engines: {node: '>=7.0.0'} + + color-name@1.1.4: + resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==} + + csstype@3.1.3: + resolution: {integrity: sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==} + + decamelize-keys@1.1.1: + resolution: {integrity: sha512-WiPxgEirIV0/eIOMcnFBA3/IJZAZqKnwAwWyvvdi4lsr1WCN22nhdf/3db3DoZcUjTV2SqfzIwNyp6y2xs3nmg==} + engines: {node: '>=0.10.0'} + + decamelize@1.2.0: + resolution: {integrity: sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==} + engines: {node: '>=0.10.0'} + + diff-sequences@29.6.3: + resolution: {integrity: sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q==} + engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} + + dir-glob@3.0.1: + resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==} + engines: {node: '>=8'} + + emoji-regex@8.0.0: + resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==} + + error-ex@1.3.4: + resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==} + + eslint-formatter-pretty@4.1.0: + resolution: {integrity: sha512-IsUTtGxF1hrH6lMWiSl1WbGaiP01eT6kzywdY1U+zLc0MP+nwEnUiS9UI8IaOTUhTeQJLlCEWIbXINBH4YJbBQ==} + engines: {node: '>=10'} + + eslint-rule-docs@1.1.235: + resolution: {integrity: sha512-+TQ+x4JdTnDoFEXXb3fDvfGOwnyNV7duH8fXWTPD1ieaBmB8omj7Gw/pMBBu4uI2uJCCU8APDaQJzWuXnTsH4A==} + + fast-glob@3.3.3: + resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==} + engines: {node: '>=8.6.0'} + + fastq@1.19.1: + resolution: {integrity: sha512-GwLTyxkCXjXbxqIhTsMI2Nui8huMPtnxg7krajPJAjnEG/iiOS7i+zCtWGZR9G0NBKbXKh6X9m9UIsYX/N6vvQ==} + + fill-range@7.1.1: + resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==} + engines: {node: '>=8'} + + find-up@4.1.0: + resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==} + engines: {node: '>=8'} + + function-bind@1.1.2: + resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==} + + glob-parent@5.1.2: + resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==} + engines: {node: '>= 6'} + + globby@11.1.0: + resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==} + engines: {node: '>=10'} + + hard-rejection@2.1.0: + resolution: {integrity: sha512-VIZB+ibDhx7ObhAe7OVtoEbuP4h/MuOTHJ+J8h/eBXotJYl0fBgR72xDFCKgIh22OJZIOVNxBMWuhAr10r8HdA==} + engines: {node: '>=6'} + + has-flag@4.0.0: + resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==} + engines: {node: '>=8'} + + hasown@2.0.2: + resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==} + engines: {node: '>= 0.4'} + + hosted-git-info@2.8.9: + resolution: {integrity: sha512-mxIDAb9Lsm6DoOJ7xH+5+X4y1LU/4Hi50L9C5sIswK3JzULS4bwk1FvjdBgvYR4bzT4tuUQiC15FE2f5HbLvYw==} + + hosted-git-info@4.1.0: + resolution: {integrity: sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA==} + engines: {node: '>=10'} + + ignore@5.3.2: + resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==} + engines: {node: '>= 4'} + + indent-string@4.0.0: + resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==} + engines: {node: '>=8'} + + irregular-plurals@3.5.0: + resolution: {integrity: sha512-1ANGLZ+Nkv1ptFb2pa8oG8Lem4krflKuX/gINiHJHjJUKaJHk/SXk5x6K3J+39/p0h1RQ2saROclJJ+QLvETCQ==} + engines: {node: '>=8'} + + is-arrayish@0.2.1: + resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==} + + is-core-module@2.16.1: + resolution: {integrity: sha512-UfoeMA6fIJ8wTYFEUjelnaGI67v6+N7qXJEvQuIGa99l4xsCruSYOVSQ0uPANn4dAzm8lkYPaKLrrijLq7x23w==} + engines: {node: '>= 0.4'} + + is-extglob@2.1.1: + resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==} + engines: {node: '>=0.10.0'} + + is-fullwidth-code-point@3.0.0: + resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==} + engines: {node: '>=8'} + + is-glob@4.0.3: + resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==} + engines: {node: '>=0.10.0'} + + is-number@7.0.0: + resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==} + engines: {node: '>=0.12.0'} + + is-plain-obj@1.1.0: + resolution: {integrity: sha512-yvkRyxmFKEOQ4pNXCmJG5AEQNlXJS5LaONXo5/cLdTZdWvsZ1ioJEonLGAosKlMWE8lwUy/bJzMjcw8az73+Fg==} + engines: {node: '>=0.10.0'} + + is-unicode-supported@0.1.0: + resolution: {integrity: sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw==} + engines: {node: '>=10'} + + jest-diff@29.7.0: + resolution: {integrity: sha512-LMIgiIrhigmPrs03JHpxUh2yISK3vLFPkAodPeo0+BuF7wA2FoQbkEg1u8gBYBThncu7e1oEDUfIXVuTqLRUjw==} + engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} + + jest-get-type@29.6.3: + resolution: {integrity: sha512-zrteXnqYxfQh7l5FHyL38jL39di8H8rHoecLH3JNxH3BwOrBsNeabdap5e0I23lD4HHI8W5VFBZqG4Eaq5LNcw==} + engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} + + js-tokens@4.0.0: + resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} + + json-parse-even-better-errors@2.3.1: + resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==} + + kind-of@6.0.3: + resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==} + engines: {node: '>=0.10.0'} + + lines-and-columns@1.2.4: + resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} + + locate-path@5.0.0: + resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==} + engines: {node: '>=8'} + + log-symbols@4.1.0: + resolution: {integrity: sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==} + engines: {node: '>=10'} + + lru-cache@6.0.0: + resolution: {integrity: sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==} + engines: {node: '>=10'} + + map-obj@1.0.1: + resolution: {integrity: sha512-7N/q3lyZ+LVCp7PzuxrJr4KMbBE2hW7BT7YNia330OFxIf4d3r5zVpicP2650l7CPN6RM9zOJRl3NGpqSiw3Eg==} + engines: {node: '>=0.10.0'} + + map-obj@4.3.0: + resolution: {integrity: sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==} + engines: {node: '>=8'} + + meow@9.0.0: + resolution: {integrity: sha512-+obSblOQmRhcyBt62furQqRAQpNyWXo8BuQ5bN7dG8wmwQ+vwHKp/rCFD4CrTP8CsDQD1sjoZ94K417XEUk8IQ==} + engines: {node: '>=10'} + + merge2@1.4.1: + resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==} + engines: {node: '>= 8'} + + micromatch@4.0.8: + resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==} + engines: {node: '>=8.6'} + + min-indent@1.0.1: + resolution: {integrity: sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==} + engines: {node: '>=4'} + + minimist-options@4.1.0: + resolution: {integrity: sha512-Q4r8ghd80yhO/0j1O3B2BjweX3fiHg9cdOwjJd2J76Q135c+NDxGCqdYKQ1SKBuFfgWbAUzBfvYjPUEeNgqN1A==} + engines: {node: '>= 6'} + + normalize-package-data@2.5.0: + resolution: {integrity: sha512-/5CMN3T0R4XTj4DcGaexo+roZSdSFW/0AOOTROrjxzCG1wrWXEsGbRKevjlIL+ZDE4sZlJr5ED4YW0yqmkK+eA==} + + normalize-package-data@3.0.3: + resolution: {integrity: sha512-p2W1sgqij3zMMyRC067Dg16bfzVH+w7hyegmpIvZ4JNjqtGOVAIvLmjBx3yP7YTe9vKJgkoNOPjwQGogDoMXFA==} + engines: {node: '>=10'} + + p-limit@2.3.0: + resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==} + engines: {node: '>=6'} + + p-locate@4.1.0: + resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==} + engines: {node: '>=8'} + + p-try@2.2.0: + resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==} + engines: {node: '>=6'} + + parse-json@5.2.0: + resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==} + engines: {node: '>=8'} + + path-exists@4.0.0: + resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==} + engines: {node: '>=8'} + + path-parse@1.0.7: + resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==} + + path-type@4.0.0: + resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==} + engines: {node: '>=8'} + + picocolors@1.1.1: + resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==} + + picomatch@2.3.1: + resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==} + engines: {node: '>=8.6'} + + plur@4.0.0: + resolution: {integrity: sha512-4UGewrYgqDFw9vV6zNV+ADmPAUAfJPKtGvb/VdpQAx25X5f3xXdGdyOEVFwkl8Hl/tl7+xbeHqSEM+D5/TirUg==} + engines: {node: '>=10'} + + pretty-format@29.7.0: + resolution: {integrity: sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==} + engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0} + + queue-microtask@1.2.3: + resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==} + + quick-lru@4.0.1: + resolution: {integrity: sha512-ARhCpm70fzdcvNQfPoy49IaanKkTlRWF2JMzqhcJbhSFRZv7nPTvZJdcY7301IPmvW+/p0RgIWnQDLJxifsQ7g==} + engines: {node: '>=8'} + + react-is@18.3.1: + resolution: {integrity: sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==} + + read-pkg-up@7.0.1: + resolution: {integrity: sha512-zK0TB7Xd6JpCLmlLmufqykGE+/TlOePD6qKClNW7hHDKFh/J7/7gCWGR7joEQEW1bKq3a3yUZSObOoWLFQ4ohg==} + engines: {node: '>=8'} + + read-pkg@5.2.0: + resolution: {integrity: sha512-Ug69mNOpfvKDAc2Q8DRpMjjzdtrnv9HcSMX+4VsZxD1aZ6ZzrIE7rlzXBtWTyhULSMKg076AW6WR5iZpD0JiOg==} + engines: {node: '>=8'} + + redent@3.0.0: + resolution: {integrity: sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==} + engines: {node: '>=8'} + + resolve@1.22.10: + resolution: {integrity: sha512-NPRy+/ncIMeDlTAsuqwKIiferiawhefFJtkNSW0qZJEqMEb+qBt/77B/jGeeek+F0uOeN05CDa6HXbbIgtVX4w==} + engines: {node: '>= 0.4'} + hasBin: true + + reusify@1.1.0: + resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==} + engines: {iojs: '>=1.0.0', node: '>=0.10.0'} + + run-parallel@1.2.0: + resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==} + + semver@5.7.2: + resolution: {integrity: sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==} + hasBin: true + + semver@7.7.2: + resolution: {integrity: sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==} + engines: {node: '>=10'} + hasBin: true + + slash@3.0.0: + resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==} + engines: {node: '>=8'} + + spdx-correct@3.2.0: + resolution: {integrity: sha512-kN9dJbvnySHULIluDHy32WHRUu3Og7B9sbY7tsFLctQkIqnMh3hErYgdMjTYuqmcXX+lK5T1lnUt3G7zNswmZA==} + + spdx-exceptions@2.5.0: + resolution: {integrity: sha512-PiU42r+xO4UbUS1buo3LPJkjlO7430Xn5SVAhdpzzsPHsjbYVflnnFdATgabnLude+Cqu25p6N+g2lw/PFsa4w==} + + spdx-expression-parse@3.0.1: + resolution: {integrity: sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==} + + spdx-license-ids@3.0.22: + resolution: {integrity: sha512-4PRT4nh1EImPbt2jASOKHX7PB7I+e4IWNLvkKFDxNhJlfjbYlleYQh285Z/3mPTHSAK/AvdMmw5BNNuYH8ShgQ==} + + spdx-license-list@6.10.0: + resolution: {integrity: sha512-wF3RhDFoqdu14d1Prv6c8aNU0FSRuSFJpNjWeygIZcNZEwPxp7I5/Hwo8j6lSkBKWAIkSQrKefrC5N0lvOP0Gw==} + engines: {node: '>=8'} + + string-width@4.2.3: + resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==} + engines: {node: '>=8'} + + strip-ansi@6.0.1: + resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==} + engines: {node: '>=8'} + + strip-indent@3.0.0: + resolution: {integrity: sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==} + engines: {node: '>=8'} + + supports-color@7.2.0: + resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==} + engines: {node: '>=8'} + + supports-hyperlinks@2.3.0: + resolution: {integrity: sha512-RpsAZlpWcDwOPQA22aCH4J0t7L8JmAvsCxfOSEwm7cQs3LshN36QaTkwd70DnBOXDWGssw2eUoc8CaRWT0XunA==} + engines: {node: '>=8'} + + supports-preserve-symlinks-flag@1.0.0: + resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==} + engines: {node: '>= 0.4'} + + to-regex-range@5.0.1: + resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==} + engines: {node: '>=8.0'} + + trim-newlines@3.0.1: + resolution: {integrity: sha512-c1PTsA3tYrIsLGkJkzHF+w9F2EyxfXGo4UyJc4pFL++FMjnq0HJS69T3M7d//gKrFKwy429bouPescbjecU+Zw==} + engines: {node: '>=8'} + + tsd@0.33.0: + resolution: {integrity: sha512-/PQtykJFVw90QICG7zyPDMIyueOXKL7jOJVoX5pILnb3Ux+7QqynOxfVvarE+K+yi7BZyOSY4r+OZNWSWRiEwQ==} + engines: {node: '>=14.16'} + hasBin: true + + type-fest@0.18.1: + resolution: {integrity: sha512-OIAYXk8+ISY+qTOwkHtKqzAuxchoMiD9Udx+FSGQDuiRR+PJKJHc2NJAXlbhkGwTt/4/nKZxELY1w3ReWOL8mw==} + engines: {node: '>=10'} + + type-fest@0.21.3: + resolution: {integrity: sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==} + engines: {node: '>=10'} + + type-fest@0.6.0: + resolution: {integrity: sha512-q+MB8nYR1KDLrgr4G5yemftpMC7/QLqVndBmEEdqzmNj5dcFOO4Oo8qlwZE3ULT3+Zim1F8Kq4cBnikNhlCMlg==} + engines: {node: '>=8'} + + type-fest@0.8.1: + resolution: {integrity: sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==} + engines: {node: '>=8'} + + typescript@5.9.2: + resolution: {integrity: sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==} + engines: {node: '>=14.17'} + hasBin: true + + undici-types@7.12.0: + resolution: {integrity: sha512-goOacqME2GYyOZZfb5Lgtu+1IDmAlAEu5xnD3+xTzS10hT0vzpf0SPjkXwAw9Jm+4n/mQGDP3LO8CPbYROeBfQ==} + + validate-npm-package-license@3.0.4: + resolution: {integrity: sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew==} + + yallist@4.0.0: + resolution: {integrity: sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==} + + yargs-parser@20.2.9: + resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==} + engines: {node: '>=10'} + +snapshots: + + '@babel/code-frame@7.27.1': + dependencies: + '@babel/helper-validator-identifier': 7.27.1 + js-tokens: 4.0.0 + picocolors: 1.1.1 + + '@babel/helper-validator-identifier@7.27.1': {} + + '@biomejs/biome@2.2.4': + optionalDependencies: + '@biomejs/cli-darwin-arm64': 2.2.4 + '@biomejs/cli-darwin-x64': 2.2.4 + '@biomejs/cli-linux-arm64': 2.2.4 + '@biomejs/cli-linux-arm64-musl': 2.2.4 + '@biomejs/cli-linux-x64': 2.2.4 + '@biomejs/cli-linux-x64-musl': 2.2.4 + '@biomejs/cli-win32-arm64': 2.2.4 + '@biomejs/cli-win32-x64': 2.2.4 + + '@biomejs/cli-darwin-arm64@2.2.4': + optional: true + + '@biomejs/cli-darwin-x64@2.2.4': + optional: true + + '@biomejs/cli-linux-arm64-musl@2.2.4': + optional: true + + '@biomejs/cli-linux-arm64@2.2.4': + optional: true + + '@biomejs/cli-linux-x64-musl@2.2.4': + optional: true + + '@biomejs/cli-linux-x64@2.2.4': + optional: true + + '@biomejs/cli-win32-arm64@2.2.4': + optional: true + + '@biomejs/cli-win32-x64@2.2.4': + optional: true + + '@jest/schemas@29.6.3': + dependencies: + '@sinclair/typebox': 0.27.8 + + '@nodelib/fs.scandir@2.1.5': + dependencies: + '@nodelib/fs.stat': 2.0.5 + run-parallel: 1.2.0 + + '@nodelib/fs.stat@2.0.5': {} + + '@nodelib/fs.walk@1.2.8': + dependencies: + '@nodelib/fs.scandir': 2.1.5 + fastq: 1.19.1 + + '@sinclair/typebox@0.27.8': {} + + '@tsd/typescript@5.9.2': {} + + '@types/bun@1.2.22(@types/react@19.1.13)': + dependencies: + bun-types: 1.2.22(@types/react@19.1.13) + transitivePeerDependencies: + - '@types/react' + + '@types/eslint@7.29.0': + dependencies: + '@types/estree': 1.0.8 + '@types/json-schema': 7.0.15 + + '@types/estree@1.0.8': {} + + '@types/json-schema@7.0.15': {} + + '@types/minimist@1.2.5': {} + + '@types/node@24.5.2': + dependencies: + undici-types: 7.12.0 + + '@types/normalize-package-data@2.4.4': {} + + '@types/react@19.1.13': + dependencies: + csstype: 3.1.3 + + ansi-escapes@4.3.2: + dependencies: + type-fest: 0.21.3 + + ansi-regex@5.0.1: {} + + ansi-styles@4.3.0: + dependencies: + color-convert: 2.0.1 + + ansi-styles@5.2.0: {} + + array-union@2.1.0: {} + + arrify@1.0.1: {} + + braces@3.0.3: + dependencies: + fill-range: 7.1.1 + + bun-types@1.2.22(@types/react@19.1.13): + dependencies: + '@types/node': 24.5.2 + '@types/react': 19.1.13 + + camelcase-keys@6.2.2: + dependencies: + camelcase: 5.3.1 + map-obj: 4.3.0 + quick-lru: 4.0.1 + + camelcase@5.3.1: {} + + chalk@4.1.2: + dependencies: + ansi-styles: 4.3.0 + supports-color: 7.2.0 + + color-convert@2.0.1: + dependencies: + color-name: 1.1.4 + + color-name@1.1.4: {} + + csstype@3.1.3: {} + + decamelize-keys@1.1.1: + dependencies: + decamelize: 1.2.0 + map-obj: 1.0.1 + + decamelize@1.2.0: {} + + diff-sequences@29.6.3: {} + + dir-glob@3.0.1: + dependencies: + path-type: 4.0.0 + + emoji-regex@8.0.0: {} + + error-ex@1.3.4: + dependencies: + is-arrayish: 0.2.1 + + eslint-formatter-pretty@4.1.0: + dependencies: + '@types/eslint': 7.29.0 + ansi-escapes: 4.3.2 + chalk: 4.1.2 + eslint-rule-docs: 1.1.235 + log-symbols: 4.1.0 + plur: 4.0.0 + string-width: 4.2.3 + supports-hyperlinks: 2.3.0 + + eslint-rule-docs@1.1.235: {} + + fast-glob@3.3.3: + dependencies: + '@nodelib/fs.stat': 2.0.5 + '@nodelib/fs.walk': 1.2.8 + glob-parent: 5.1.2 + merge2: 1.4.1 + micromatch: 4.0.8 + + fastq@1.19.1: + dependencies: + reusify: 1.1.0 + + fill-range@7.1.1: + dependencies: + to-regex-range: 5.0.1 + + find-up@4.1.0: + dependencies: + locate-path: 5.0.0 + path-exists: 4.0.0 + + function-bind@1.1.2: {} + + glob-parent@5.1.2: + dependencies: + is-glob: 4.0.3 + + globby@11.1.0: + dependencies: + array-union: 2.1.0 + dir-glob: 3.0.1 + fast-glob: 3.3.3 + ignore: 5.3.2 + merge2: 1.4.1 + slash: 3.0.0 + + hard-rejection@2.1.0: {} + + has-flag@4.0.0: {} + + hasown@2.0.2: + dependencies: + function-bind: 1.1.2 + + hosted-git-info@2.8.9: {} + + hosted-git-info@4.1.0: + dependencies: + lru-cache: 6.0.0 + + ignore@5.3.2: {} + + indent-string@4.0.0: {} + + irregular-plurals@3.5.0: {} + + is-arrayish@0.2.1: {} + + is-core-module@2.16.1: + dependencies: + hasown: 2.0.2 + + is-extglob@2.1.1: {} + + is-fullwidth-code-point@3.0.0: {} + + is-glob@4.0.3: + dependencies: + is-extglob: 2.1.1 + + is-number@7.0.0: {} + + is-plain-obj@1.1.0: {} + + is-unicode-supported@0.1.0: {} + + jest-diff@29.7.0: + dependencies: + chalk: 4.1.2 + diff-sequences: 29.6.3 + jest-get-type: 29.6.3 + pretty-format: 29.7.0 + + jest-get-type@29.6.3: {} + + js-tokens@4.0.0: {} + + json-parse-even-better-errors@2.3.1: {} + + kind-of@6.0.3: {} + + lines-and-columns@1.2.4: {} + + locate-path@5.0.0: + dependencies: + p-locate: 4.1.0 + + log-symbols@4.1.0: + dependencies: + chalk: 4.1.2 + is-unicode-supported: 0.1.0 + + lru-cache@6.0.0: + dependencies: + yallist: 4.0.0 + + map-obj@1.0.1: {} + + map-obj@4.3.0: {} + + meow@9.0.0: + dependencies: + '@types/minimist': 1.2.5 + camelcase-keys: 6.2.2 + decamelize: 1.2.0 + decamelize-keys: 1.1.1 + hard-rejection: 2.1.0 + minimist-options: 4.1.0 + normalize-package-data: 3.0.3 + read-pkg-up: 7.0.1 + redent: 3.0.0 + trim-newlines: 3.0.1 + type-fest: 0.18.1 + yargs-parser: 20.2.9 + + merge2@1.4.1: {} + + micromatch@4.0.8: + dependencies: + braces: 3.0.3 + picomatch: 2.3.1 + + min-indent@1.0.1: {} + + minimist-options@4.1.0: + dependencies: + arrify: 1.0.1 + is-plain-obj: 1.1.0 + kind-of: 6.0.3 + + normalize-package-data@2.5.0: + dependencies: + hosted-git-info: 2.8.9 + resolve: 1.22.10 + semver: 5.7.2 + validate-npm-package-license: 3.0.4 + + normalize-package-data@3.0.3: + dependencies: + hosted-git-info: 4.1.0 + is-core-module: 2.16.1 + semver: 7.7.2 + validate-npm-package-license: 3.0.4 + + p-limit@2.3.0: + dependencies: + p-try: 2.2.0 + + p-locate@4.1.0: + dependencies: + p-limit: 2.3.0 + + p-try@2.2.0: {} + + parse-json@5.2.0: + dependencies: + '@babel/code-frame': 7.27.1 + error-ex: 1.3.4 + json-parse-even-better-errors: 2.3.1 + lines-and-columns: 1.2.4 + + path-exists@4.0.0: {} + + path-parse@1.0.7: {} + + path-type@4.0.0: {} + + picocolors@1.1.1: {} + + picomatch@2.3.1: {} + + plur@4.0.0: + dependencies: + irregular-plurals: 3.5.0 + + pretty-format@29.7.0: + dependencies: + '@jest/schemas': 29.6.3 + ansi-styles: 5.2.0 + react-is: 18.3.1 + + queue-microtask@1.2.3: {} + + quick-lru@4.0.1: {} + + react-is@18.3.1: {} + + read-pkg-up@7.0.1: + dependencies: + find-up: 4.1.0 + read-pkg: 5.2.0 + type-fest: 0.8.1 + + read-pkg@5.2.0: + dependencies: + '@types/normalize-package-data': 2.4.4 + normalize-package-data: 2.5.0 + parse-json: 5.2.0 + type-fest: 0.6.0 + + redent@3.0.0: + dependencies: + indent-string: 4.0.0 + strip-indent: 3.0.0 + + resolve@1.22.10: + dependencies: + is-core-module: 2.16.1 + path-parse: 1.0.7 + supports-preserve-symlinks-flag: 1.0.0 + + reusify@1.1.0: {} + + run-parallel@1.2.0: + dependencies: + queue-microtask: 1.2.3 + + semver@5.7.2: {} + + semver@7.7.2: {} + + slash@3.0.0: {} + + spdx-correct@3.2.0: + dependencies: + spdx-expression-parse: 3.0.1 + spdx-license-ids: 3.0.22 + + spdx-exceptions@2.5.0: {} + + spdx-expression-parse@3.0.1: + dependencies: + spdx-exceptions: 2.5.0 + spdx-license-ids: 3.0.22 + + spdx-license-ids@3.0.22: {} + + spdx-license-list@6.10.0: {} + + string-width@4.2.3: + dependencies: + emoji-regex: 8.0.0 + is-fullwidth-code-point: 3.0.0 + strip-ansi: 6.0.1 + + strip-ansi@6.0.1: + dependencies: + ansi-regex: 5.0.1 + + strip-indent@3.0.0: + dependencies: + min-indent: 1.0.1 + + supports-color@7.2.0: + dependencies: + has-flag: 4.0.0 + + supports-hyperlinks@2.3.0: + dependencies: + has-flag: 4.0.0 + supports-color: 7.2.0 + + supports-preserve-symlinks-flag@1.0.0: {} + + to-regex-range@5.0.1: + dependencies: + is-number: 7.0.0 + + trim-newlines@3.0.1: {} + + tsd@0.33.0: + dependencies: + '@tsd/typescript': 5.9.2 + eslint-formatter-pretty: 4.1.0 + globby: 11.1.0 + jest-diff: 29.7.0 + meow: 9.0.0 + path-exists: 4.0.0 + read-pkg-up: 7.0.1 + + type-fest@0.18.1: {} + + type-fest@0.21.3: {} + + type-fest@0.6.0: {} + + type-fest@0.8.1: {} + + typescript@5.9.2: {} + + undici-types@7.12.0: {} + + validate-npm-package-license@3.0.4: + dependencies: + spdx-correct: 3.2.0 + spdx-expression-parse: 3.0.1 + + yallist@4.0.0: {} + + yargs-parser@20.2.9: {} diff --git a/tests/2.0/api-with-examples.ts b/tests/2.0/api-with-examples.ts new file mode 100644 index 0000000..847bc5f --- /dev/null +++ b/tests/2.0/api-with-examples.ts @@ -0,0 +1,147 @@ +import type { Specification } from "../../2.0"; + +const _apiWithExamples: Specification = { + swagger: "2.0", + info: { + title: "Simple API overview", + version: "v2", + }, + paths: { + "/": { + get: { + operationId: "listVersionsv2", + summary: "List API versions", + produces: ["application/json"], + responses: { + "200": { + description: "200 300 response", + examples: { + "application/json": { + versions: [ + { + status: "CURRENT", + updated: "2011-01-21T11:33:21Z", + id: "v2.0", + links: [{ href: "http://127.0.0.1:8774/v2/", rel: "self" }], + }, + { + status: "EXPERIMENTAL", + updated: "2013-07-23T11:33:21Z", + id: "v3.0", + links: [{ href: "http://127.0.0.1:8774/v3/", rel: "self" }], + }, + ], + }, + }, + }, + "300": { + description: "200 300 response", + examples: { + "application/json": { + versions: [ + { + status: "CURRENT", + updated: "2011-01-21T11:33:21Z", + id: "v2.0", + links: [{ href: "http://127.0.0.1:8774/v2/", rel: "self" }], + }, + { + status: "EXPERIMENTAL", + updated: "2013-07-23T11:33:21Z", + id: "v3.0", + links: [{ href: "http://127.0.0.1:8774/v3/", rel: "self" }], + }, + ], + }, + }, + }, + }, + }, + }, + "/v2": { + get: { + operationId: "getVersionDetailsv2", + summary: "Show API version details", + produces: ["application/json"], + responses: { + "200": { + description: "200 203 response", + examples: { + "application/json": { + version: { + status: "CURRENT", + updated: "2011-01 - 21T11: 33: 21Z", + "media - types": [ + { + base: "application / xml", + type: "application / vnd.openstack.compute + xml; version=2", + }, + { + base: "application / json", + type: "application / vnd.openstack.compute + json; version=2", + }, + ], + id: "v2.0", + links: [ + { href: "http://127.0.0.1:8774/v2/", rel: "self" }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + type: "application/pdf", + rel: "describedby", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + type: "application/vnd.sun.wadl+xml", + rel: "describedby", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + type: "application/vnd.sun.wadl+xml", + rel: "describedby", + }, + ], + }, + }, + }, + }, + "203": { + description: "200 203 response", + examples: { + "application/json": { + version: { + status: "CURRENT", + updated: "2011-01 - 21T11: 33: 21Z", + "media - types": [ + { + base: "application / xml", + type: "application / vnd.openstack.compute + xml; version=2", + }, + { + base: "application / json", + type: "application / vnd.openstack.compute + json; version=2", + }, + ], + id: "v2.0", + links: [ + { href: "http://23.253.228.211:8774/v2/", rel: "self" }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + type: "application/pdf", + rel: "describedby", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + type: "application/vnd.sun.wadl+xml", + rel: "describedby", + }, + ], + }, + }, + }, + }, + }, + }, + }, + }, + consumes: ["application/json"], +}; diff --git a/tests/2.0/petstore-expanded.ts b/tests/2.0/petstore-expanded.ts new file mode 100644 index 0000000..bbdd693 --- /dev/null +++ b/tests/2.0/petstore-expanded.ts @@ -0,0 +1,202 @@ +import type { Specification } from "../../2.0"; + +const _petstoreExpanded: Specification = { + swagger: "2.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + description: + "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", + termsOfService: "http://swagger.io/terms/", + contact: { + name: "Swagger API Team", + email: "apiteam@swagger.io", + url: "http://swagger.io", + }, + license: { + name: "Apache 2.0", + url: "https://www.apache.org/licenses/LICENSE-2.0.html", + }, + }, + host: "petstore.swagger.io", + basePath: "/api", + schemes: ["http"], + consumes: ["application/json"], + produces: ["application/json"], + paths: { + "/pets": { + get: { + description: + "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", + operationId: "findPets", + parameters: [ + { + name: "tags", + in: "query", + description: "tags to filter by", + required: false, + type: "array", + collectionFormat: "csv", + items: { + type: "string", + }, + }, + { + name: "limit", + in: "query", + description: "maximum number of results to return", + required: false, + type: "integer", + format: "int32", + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + type: "array", + items: { + $ref: "#/definitions/Pet", + }, + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + post: { + description: "Creates a new pet in the store. Duplicates are allowed", + operationId: "addPet", + parameters: [ + { + name: "pet", + in: "body", + description: "Pet to add to the store", + required: true, + schema: { + $ref: "#/definitions/NewPet", + }, + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + $ref: "#/definitions/Pet", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + "/pets/{id}": { + get: { + description: + "Returns a user based on a single ID, if the user does not have access to the pet", + operationId: "find pet by id", + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to fetch", + required: true, + type: "integer", + format: "int64", + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + $ref: "#/definitions/Pet", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + delete: { + description: "deletes a single pet based on the ID supplied", + operationId: "deletePet", + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to delete", + required: true, + type: "integer", + format: "int64", + }, + ], + responses: { + 204: { + description: "pet deleted", + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + }, + definitions: { + Pet: { + type: "object", + allOf: [ + { + $ref: "#/definitions/NewPet", + }, + { + required: ["id"], + properties: { + id: { + type: "integer", + format: "int64", + }, + }, + }, + ], + }, + NewPet: { + type: "object", + required: ["name"], + properties: { + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + Error: { + type: "object", + required: ["code", "message"], + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + }, + }, + }, +}; diff --git a/tests/2.0/petstore-minimal.ts b/tests/2.0/petstore-minimal.ts new file mode 100644 index 0000000..5252816 --- /dev/null +++ b/tests/2.0/petstore-minimal.ts @@ -0,0 +1,61 @@ +import type { Specification } from "../../2.0"; + +const _petstoreMinimal: Specification = { + swagger: "2.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + description: + "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", + termsOfService: "http://swagger.io/terms/", + contact: { + name: "Swagger API Team", + }, + license: { + name: "MIT", + }, + }, + host: "petstore.swagger.io", + basePath: "/api", + schemes: ["http"], + consumes: ["application/json"], + produces: ["application/json"], + paths: { + "/pets": { + get: { + description: + "Returns all pets from the system that the user has access to", + produces: ["application/json"], + responses: { + 200: { + description: "A list of pets.", + schema: { + type: "array", + items: { + $ref: "#/definitions/Pet", + }, + }, + }, + }, + }, + }, + }, + definitions: { + Pet: { + type: "object", + required: ["id", "name"], + properties: { + id: { + type: "integer", + format: "int64", + }, + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + }, +}; diff --git a/tests/2.0/petstore-simple.ts b/tests/2.0/petstore-simple.ts new file mode 100644 index 0000000..981b141 --- /dev/null +++ b/tests/2.0/petstore-simple.ts @@ -0,0 +1,212 @@ +import type { Specification } from "../../2.0"; + +const _petstoreSimple: Specification = { + swagger: "2.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + description: + "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", + termsOfService: "http://swagger.io/terms/", + contact: { + name: "Swagger API Team", + }, + license: { + name: "MIT", + }, + }, + host: "petstore.swagger.io", + basePath: "/api", + schemes: ["http"], + consumes: ["application/json"], + produces: ["application/json"], + paths: { + "/pets": { + get: { + description: + "Returns all pets from the system that the user has access to", + operationId: "findPets", + produces: [ + "application/json", + "application/xml", + "text/xml", + "text/html", + ], + parameters: [ + { + name: "tags", + in: "query", + description: "tags to filter by", + required: false, + type: "array", + items: { + type: "string", + }, + collectionFormat: "csv", + }, + { + name: "limit", + in: "query", + description: "maximum number of results to return", + required: false, + type: "integer", + format: "int32", + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + type: "array", + items: { + $ref: "#/definitions/Pet", + }, + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + post: { + description: "Creates a new pet in the store. Duplicates are allowed", + operationId: "addPet", + produces: ["application/json"], + parameters: [ + { + name: "pet", + in: "body", + description: "Pet to add to the store", + required: true, + schema: { + $ref: "#/definitions/NewPet", + }, + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + $ref: "#/definitions/Pet", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + }, + "/pets/{id}": { + get: { + description: + "Returns a user based on a single ID, if the user does not have access to the pet", + operationId: "findPetById", + produces: [ + "application/json", + "application/xml", + "text/xml", + "text/html", + ], + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to fetch", + required: true, + type: "integer", + format: "int64", + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + $ref: "#/definitions/Pet", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + delete: { + description: "deletes a single pet based on the ID supplied", + operationId: "deletePet", + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to delete", + required: true, + type: "integer", + format: "int64", + }, + ], + responses: { + 204: { + description: "pet deleted", + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + }, + }, + definitions: { + Pet: { + type: "object", + allOf: [ + { + $ref: "#/definitions/NewPet", + }, + { + required: ["id"], + properties: { + id: { + type: "integer", + format: "int64", + }, + }, + }, + ], + }, + NewPet: { + type: "object", + required: ["name"], + properties: { + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + ErrorModel: { + type: "object", + required: ["code", "message"], + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + }, + }, + }, +}; diff --git a/tests/2.0/petstore-with-external-docs.ts b/tests/2.0/petstore-with-external-docs.ts new file mode 100644 index 0000000..c00e399 --- /dev/null +++ b/tests/2.0/petstore-with-external-docs.ts @@ -0,0 +1,223 @@ +import type { Specification } from "../../2.0"; + +const _petstoreWithExternalDocs: Specification = { + swagger: "2.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + description: + "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", + termsOfService: "http://swagger.io/terms/", + contact: { + name: "Swagger API Team", + email: "apiteam@swagger.io", + url: "http://swagger.io", + }, + license: { + name: "Apache 2.0", + url: "https://www.apache.org/licenses/LICENSE-2.0.html", + }, + }, + externalDocs: { + description: "find more info here", + url: "https://swagger.io/about", + }, + host: "petstore.swagger.io", + basePath: "/api", + schemes: ["http"], + consumes: ["application/json"], + produces: ["application/json"], + paths: { + "/pets": { + get: { + description: + "Returns all pets from the system that the user has access to", + operationId: "findPets", + externalDocs: { + description: "find more info here", + url: "https://swagger.io/about", + }, + produces: [ + "application/json", + "application/xml", + "text/xml", + "text/html", + ], + parameters: [ + { + name: "tags", + in: "query", + description: "tags to filter by", + required: false, + type: "array", + items: { + type: "string", + }, + collectionFormat: "csv", + }, + { + name: "limit", + in: "query", + description: "maximum number of results to return", + required: false, + type: "integer", + format: "int32", + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + type: "array", + items: { + $ref: "#/definitions/Pet", + }, + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + post: { + description: "Creates a new pet in the store. Duplicates are allowed", + operationId: "addPet", + produces: ["application/json"], + parameters: [ + { + name: "pet", + in: "body", + description: "Pet to add to the store", + required: true, + schema: { + $ref: "#/definitions/NewPet", + }, + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + $ref: "#/definitions/Pet", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + }, + "/pets/{id}": { + get: { + description: + "Returns a user based on a single ID, if the user does not have access to the pet", + operationId: "findPetById", + produces: [ + "application/json", + "application/xml", + "text/xml", + "text/html", + ], + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to fetch", + required: true, + type: "integer", + format: "int64", + }, + ], + responses: { + 200: { + description: "pet response", + schema: { + $ref: "#/definitions/Pet", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + delete: { + description: "deletes a single pet based on the ID supplied", + operationId: "deletePet", + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to delete", + required: true, + type: "integer", + format: "int64", + }, + ], + responses: { + 204: { + description: "pet deleted", + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/ErrorModel", + }, + }, + }, + }, + }, + }, + definitions: { + Pet: { + type: "object", + allOf: [ + { + $ref: "#/definitions/NewPet", + }, + { + required: ["id"], + properties: { + id: { + type: "integer", + format: "int64", + }, + }, + }, + ], + }, + NewPet: { + type: "object", + required: ["name"], + properties: { + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + ErrorModel: { + type: "object", + required: ["code", "message"], + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + }, + }, + }, +}; diff --git a/tests/2.0/petstore.ts b/tests/2.0/petstore.ts new file mode 100644 index 0000000..e0291e5 --- /dev/null +++ b/tests/2.0/petstore.ts @@ -0,0 +1,137 @@ +import type { Specification } from "../../2.0"; + +const _petstore: Specification = { + swagger: "2.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + license: { + name: "MIT", + }, + }, + host: "petstore.swagger.io", + basePath: "/v1", + schemes: ["http"], + consumes: ["application/json"], + produces: ["application/json"], + paths: { + "/pets": { + get: { + summary: "List all pets", + operationId: "listPets", + tags: ["pets"], + parameters: [ + { + name: "limit", + in: "query", + description: "How many items to return at one time (max 100)", + required: false, + type: "integer", + format: "int32", + }, + ], + responses: { + 200: { + description: "An paged array of pets", + headers: { + "x-next": { + type: "string", + description: "A link to the next page of responses", + }, + }, + schema: { + $ref: "#/definitions/Pets", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + post: { + summary: "Create a pet", + operationId: "createPets", + tags: ["pets"], + responses: { + 201: { + description: "Null response", + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + "/pets/{petId}": { + get: { + summary: "Info for a specific pet", + operationId: "showPetById", + tags: ["pets"], + parameters: [ + { + name: "petId", + in: "path", + required: true, + description: "The id of the pet to retrieve", + type: "string", + }, + ], + responses: { + 200: { + description: "Expected response to a valid request", + schema: { + $ref: "#/definitions/Pets", + }, + }, + default: { + description: "unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + }, + definitions: { + Pet: { + required: ["id", "name"], + properties: { + id: { + type: "integer", + format: "int64", + }, + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + Pets: { + type: "array", + items: { + $ref: "#/definitions/Pet", + }, + }, + Error: { + required: ["code", "message"], + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + }, + }, + }, +}; diff --git a/tests/2.0/uber.ts b/tests/2.0/uber.ts new file mode 100644 index 0000000..f6534ef --- /dev/null +++ b/tests/2.0/uber.ts @@ -0,0 +1,372 @@ +import type { Specification } from "../../2.0"; + +const _uber: Specification = { + swagger: "2.0", + info: { + title: "Uber API", + description: "Move your app forward with the Uber API", + version: "1.0.0", + }, + host: "api.uber.com", + schemes: ["https"], + basePath: "/v1", + produces: ["application/json"], + paths: { + "/products": { + get: { + summary: "Product Types", + description: + "The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.", + parameters: [ + { + name: "latitude", + in: "query", + description: "Latitude component of location.", + required: true, + type: "number", + format: "double", + }, + { + name: "longitude", + in: "query", + description: "Longitude component of location.", + required: true, + type: "number", + format: "double", + }, + ], + tags: ["Products"], + responses: { + 200: { + description: "An array of products", + schema: { + type: "array", + items: { + $ref: "#/definitions/Product", + }, + }, + }, + default: { + description: "Unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + "/estimates/price": { + get: { + summary: "Price Estimates", + description: + "The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.", + parameters: [ + { + name: "start_latitude", + in: "query", + description: "Latitude component of start location.", + required: true, + type: "number", + format: "double", + }, + { + name: "start_longitude", + in: "query", + description: "Longitude component of start location.", + required: true, + type: "number", + format: "double", + }, + { + name: "end_latitude", + in: "query", + description: "Latitude component of end location.", + required: true, + type: "number", + format: "double", + }, + { + name: "end_longitude", + in: "query", + description: "Longitude component of end location.", + required: true, + type: "number", + format: "double", + }, + ], + tags: ["Estimates"], + responses: { + 200: { + description: "An array of price estimates by product", + schema: { + type: "array", + items: { + $ref: "#/definitions/PriceEstimate", + }, + }, + }, + default: { + description: "Unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + "/estimates/time": { + get: { + summary: "Time Estimates", + description: + "The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.", + parameters: [ + { + name: "start_latitude", + in: "query", + description: "Latitude component of start location.", + required: true, + type: "number", + format: "double", + }, + { + name: "start_longitude", + in: "query", + description: "Longitude component of start location.", + required: true, + type: "number", + format: "double", + }, + { + name: "customer_uuid", + in: "query", + type: "string", + format: "uuid", + description: + "Unique customer identifier to be used for experience customization.", + }, + { + name: "product_id", + in: "query", + type: "string", + description: + "Unique identifier representing a specific product for a given latitude & longitude.", + }, + ], + tags: ["Estimates"], + responses: { + 200: { + description: "An array of products", + schema: { + type: "array", + items: { + $ref: "#/definitions/Product", + }, + }, + }, + default: { + description: "Unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + "/me": { + get: { + summary: "User Profile", + description: + "The User Profile endpoint returns information about the Uber user that has authorized with the application.", + tags: ["User"], + responses: { + 200: { + description: "Profile information for a user", + schema: { + $ref: "#/definitions/Profile", + }, + }, + default: { + description: "Unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + "/history": { + get: { + summary: "User Activity", + description: + "The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.", + parameters: [ + { + name: "offset", + in: "query", + type: "integer", + format: "int32", + description: + "Offset the list of returned results by this amount. Default is zero.", + }, + { + name: "limit", + in: "query", + type: "integer", + format: "int32", + description: + "Number of items to retrieve. Default is 5, maximum is 100.", + }, + ], + tags: ["User"], + responses: { + 200: { + description: "History information for the given user", + schema: { + $ref: "#/definitions/Activities", + }, + }, + default: { + description: "Unexpected error", + schema: { + $ref: "#/definitions/Error", + }, + }, + }, + }, + }, + }, + definitions: { + Product: { + properties: { + product_id: { + type: "string", + description: + "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.", + }, + description: { + type: "string", + description: "Description of product.", + }, + display_name: { + type: "string", + description: "Display name of product.", + }, + capacity: { + type: "string", + description: "Capacity of product. For example, 4 people.", + }, + image: { + type: "string", + description: "Image URL representing the product.", + }, + }, + }, + PriceEstimate: { + properties: { + product_id: { + type: "string", + description: + "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles", + }, + currency_code: { + type: "string", + description: + "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code.", + }, + display_name: { + type: "string", + description: "Display name of product.", + }, + estimate: { + type: "string", + description: + 'Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or "Metered" for TAXI.', + }, + low_estimate: { + type: "number", + description: "Lower bound of the estimated price.", + }, + high_estimate: { + type: "number", + description: "Upper bound of the estimated price.", + }, + surge_multiplier: { + type: "number", + description: + "Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier.", + }, + }, + }, + Profile: { + properties: { + first_name: { + type: "string", + description: "First name of the Uber user.", + }, + last_name: { + type: "string", + description: "Last name of the Uber user.", + }, + email: { + type: "string", + description: "Email address of the Uber user", + }, + picture: { + type: "string", + description: "Image URL of the Uber user.", + }, + promo_code: { + type: "string", + description: "Promo code of the Uber user.", + }, + }, + }, + Activity: { + properties: { + uuid: { + type: "string", + description: "Unique identifier for the activity", + }, + }, + }, + Activities: { + properties: { + offset: { + type: "integer", + format: "int32", + description: "Position in pagination.", + }, + limit: { + type: "integer", + format: "int32", + description: "Number of items to retrieve (100 max).", + }, + count: { + type: "integer", + format: "int32", + description: "Total number of items available.", + }, + history: { + type: "array", + items: { + $ref: "#/definitions/Activity", + }, + }, + }, + }, + Error: { + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + fields: { + type: "string", + }, + }, + }, + }, +}; diff --git a/tests/3.0/api-with-examples.ts b/tests/3.0/api-with-examples.ts new file mode 100644 index 0000000..1cdf88b --- /dev/null +++ b/tests/3.0/api-with-examples.ts @@ -0,0 +1,194 @@ +import type { Specification } from "../../3.0"; + +const _apiWithExamples: Specification = { + openapi: "3.0.0", + info: { + title: "Simple API overview", + version: "2.0.0", + }, + paths: { + "/": { + get: { + operationId: "listVersionsv2", + summary: "List API versions", + responses: { + "200": { + description: "200 response", + content: { + "application/json": { + examples: { + foo: { + value: { + versions: [ + { + status: "CURRENT", + updated: "2011-01-21T11:33:21Z", + id: "v2.0", + links: [ + { + href: "http://127.0.0.1:8774/v2/", + rel: "self", + }, + ], + }, + { + status: "EXPERIMENTAL", + updated: "2013-07-23T11:33:21Z", + id: "v3.0", + links: [ + { + href: "http://127.0.0.1:8774/v3/", + rel: "self", + }, + ], + }, + ], + }, + }, + }, + }, + }, + }, + "300": { + description: "300 response", + content: { + "application/json": { + examples: { + foo: { + value: { + versions: [ + { + status: "CURRENT", + updated: "2011-01-21T11:33:21Z", + id: "v2.0", + links: [ + { + href: "http://127.0.0.1:8774/v2/", + rel: "self", + }, + ], + }, + { + status: "EXPERIMENTAL", + updated: "2013-07-23T11:33:21Z", + id: "v3.0", + links: [ + { + href: "http://127.0.0.1:8774/v3/", + rel: "self", + }, + ], + }, + ], + }, + }, + }, + }, + }, + }, + }, + }, + }, + "/v2": { + get: { + operationId: "getVersionDetailsv2", + summary: "Show API version details", + responses: { + "200": { + description: "200 response", + content: { + "application/json": { + examples: { + foo: { + value: { + version: { + status: "CURRENT", + updated: "2011-01-21T11:33:21Z", + "media-types": [ + { + base: "application/xml", + type: "application/vnd.openstack.compute+xml;version=2", + }, + { + base: "application/json", + type: "application/vnd.openstack.compute+json;version=2", + }, + ], + id: "v2.0", + links: [ + { + href: "http://127.0.0.1:8774/v2/", + rel: "self", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + type: "application/pdf", + rel: "describedby", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + type: "application/vnd.sun.wadl+xml", + rel: "describedby", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + type: "application/vnd.sun.wadl+xml", + rel: "describedby", + }, + ], + }, + }, + }, + }, + }, + }, + }, + "203": { + description: "203 response", + content: { + "application/json": { + examples: { + foo: { + value: { + version: { + status: "CURRENT", + updated: "2011-01-21T11:33:21Z", + "media-types": [ + { + base: "application/xml", + type: "application/vnd.openstack.compute+xml;version=2", + }, + { + base: "application/json", + type: "application/vnd.openstack.compute+json;version=2", + }, + ], + id: "v2.0", + links: [ + { + href: "http://23.253.228.211:8774/v2/", + rel: "self", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + type: "application/pdf", + rel: "describedby", + }, + { + href: "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + type: "application/vnd.sun.wadl+xml", + rel: "describedby", + }, + ], + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, +}; diff --git a/tests/3.0/callback-example.ts b/tests/3.0/callback-example.ts new file mode 100644 index 0000000..48c18e1 --- /dev/null +++ b/tests/3.0/callback-example.ts @@ -0,0 +1,88 @@ +import type { Specification } from "../../3.0"; + +const _callbackExample: Specification = { + openapi: "3.0.0", + info: { + title: "Callback Example", + version: "1.0.0", + }, + paths: { + "/streams": { + post: { + description: "subscribes a client to receive out-of-band data", + parameters: [ + { + name: "callbackUrl", + in: "query", + required: true, + description: + "the location where data will be sent. Must be network accessible\nby the source server\n", + schema: { + type: "string", + format: "uri", + example: "https://tonys-server.com", + }, + }, + ], + responses: { + "201": { + description: "subscription successfully created", + content: { + "application/json": { + schema: { + description: "subscription information", + required: ["subscriptionId"], + properties: { + subscriptionId: { + description: + "this unique identifier allows management of the subscription", + type: "string", + example: "2531329f-fb09-4ef7-887e-84e648214436", + }, + }, + }, + }, + }, + }, + }, + callbacks: { + onData: { + "{$request.query.callbackUrl}/data": { + post: { + requestBody: { + description: "subscription payload", + content: { + "application/json": { + schema: { + type: "object", + properties: { + timestamp: { + type: "string", + format: "date-time", + }, + userData: { + type: "string", + }, + }, + }, + }, + }, + }, + responses: { + "202": { + description: + "Your server implementation should return this HTTP status code\nif the data was received successfully\n", + }, + "204": { + description: + "Your server should return this HTTP status code if no longer interested\nin further updates\n", + }, + }, + }, + }, + }, + }, + }, + }, + }, +}; diff --git a/tests/3.0/link-example.ts b/tests/3.0/link-example.ts new file mode 100644 index 0000000..b92f6c7 --- /dev/null +++ b/tests/3.0/link-example.ts @@ -0,0 +1,321 @@ +import type { Specification } from "../../3.0"; + +const _linkExample: Specification = { + openapi: "3.0.0", + info: { + title: "Link Example", + version: "1.0.0", + }, + paths: { + "/2.0/users/{username}": { + get: { + operationId: "getUserByName", + parameters: [ + { + name: "username", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + ], + responses: { + "200": { + description: "The User", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/user", + }, + }, + }, + links: { + userRepositories: { + $ref: "#/components/links/UserRepositories", + }, + }, + }, + }, + }, + }, + "/2.0/repositories/{username}": { + get: { + operationId: "getRepositoriesByOwner", + parameters: [ + { + name: "username", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + ], + responses: { + "200": { + description: "repositories owned by the supplied user", + content: { + "application/json": { + schema: { + type: "array", + items: { + $ref: "#/components/schemas/repository", + }, + }, + }, + }, + links: { + userRepository: { + $ref: "#/components/links/UserRepository", + }, + }, + }, + }, + }, + }, + "/2.0/repositories/{username}/{slug}": { + get: { + operationId: "getRepository", + parameters: [ + { + name: "username", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "slug", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + ], + responses: { + "200": { + description: "The repository", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/repository", + }, + }, + }, + links: { + repositoryPullRequests: { + $ref: "#/components/links/RepositoryPullRequests", + }, + }, + }, + }, + }, + }, + "/2.0/repositories/{username}/{slug}/pullrequests": { + get: { + operationId: "getPullRequestsByRepository", + parameters: [ + { + name: "username", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "slug", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "state", + in: "query", + schema: { + type: "string", + enum: ["open", "merged", "declined"], + }, + }, + ], + responses: { + "200": { + description: "an array of pull request objects", + content: { + "application/json": { + schema: { + type: "array", + items: { + $ref: "#/components/schemas/pullrequest", + }, + }, + }, + }, + }, + }, + }, + }, + "/2.0/repositories/{username}/{slug}/pullrequests/{pid}": { + get: { + operationId: "getPullRequestsById", + parameters: [ + { + name: "username", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "slug", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "pid", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + ], + responses: { + "200": { + description: "a pull request object", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/pullrequest", + }, + }, + }, + links: { + pullRequestMerge: { + $ref: "#/components/links/PullRequestMerge", + }, + }, + }, + }, + }, + }, + "/2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge": { + post: { + operationId: "mergePullRequest", + parameters: [ + { + name: "username", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "slug", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + { + name: "pid", + in: "path", + required: true, + schema: { + type: "string", + }, + }, + ], + responses: { + "204": { + description: "the PR was successfully merged", + }, + }, + }, + }, + }, + components: { + links: { + UserRepositories: { + operationId: "getRepositoriesByOwner", + parameters: { + username: "$response.body#/username", + }, + }, + UserRepository: { + operationId: "getRepository", + parameters: { + username: "$response.body#/owner/username", + slug: "$response.body#/slug", + }, + }, + RepositoryPullRequests: { + operationId: "getPullRequestsByRepository", + parameters: { + username: "$response.body#/owner/username", + slug: "$response.body#/slug", + }, + }, + PullRequestMerge: { + operationId: "mergePullRequest", + parameters: { + username: "$response.body#/author/username", + slug: "$response.body#/repository/slug", + pid: "$response.body#/id", + }, + }, + }, + schemas: { + user: { + type: "object", + properties: { + username: { + type: "string", + }, + uuid: { + type: "string", + }, + }, + }, + repository: { + type: "object", + properties: { + slug: { + type: "string", + }, + owner: { + $ref: "#/components/schemas/user", + }, + }, + }, + pullrequest: { + type: "object", + properties: { + id: { + type: "integer", + }, + title: { + type: "string", + }, + repository: { + $ref: "#/components/schemas/repository", + }, + author: { + $ref: "#/components/schemas/user", + }, + }, + }, + }, + }, +}; diff --git a/tests/3.0/petstore-expanded.ts b/tests/3.0/petstore-expanded.ts new file mode 100644 index 0000000..6b09d84 --- /dev/null +++ b/tests/3.0/petstore-expanded.ts @@ -0,0 +1,240 @@ +import type { Specification } from "../../3.0"; + +const _petstoreExpanded: Specification = { + openapi: "3.0.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + description: + "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification", + termsOfService: "http://swagger.io/terms/", + contact: { + name: "Swagger API Team", + email: "apiteam@swagger.io", + url: "http://swagger.io", + }, + license: { + name: "Apache 2.0", + url: "https://www.apache.org/licenses/LICENSE-2.0.html", + }, + }, + servers: [ + { + url: "https://petstore.swagger.io/v2", + }, + ], + paths: { + "/pets": { + get: { + description: + "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", + operationId: "findPets", + parameters: [ + { + name: "tags", + in: "query", + description: "tags to filter by", + required: false, + style: "form", + schema: { + type: "array", + items: { + type: "string", + }, + }, + }, + { + name: "limit", + in: "query", + description: "maximum number of results to return", + required: false, + schema: { + type: "integer", + format: "int32", + }, + }, + ], + responses: { + "200": { + description: "pet response", + content: { + "application/json": { + schema: { + type: "array", + items: { + $ref: "#/components/schemas/Pet", + }, + }, + }, + }, + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + post: { + description: "Creates a new pet in the store. Duplicates are allowed", + operationId: "addPet", + requestBody: { + description: "Pet to add to the store", + required: true, + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/NewPet", + }, + }, + }, + }, + responses: { + "200": { + description: "pet response", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Pet", + }, + }, + }, + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + }, + "/pets/{id}": { + get: { + description: + "Returns a user based on a single ID, if the user does not have access to the pet", + operationId: "find pet by id", + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to fetch", + required: true, + schema: { + type: "integer", + format: "int64", + }, + }, + ], + responses: { + "200": { + description: "pet response", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Pet", + }, + }, + }, + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + delete: { + description: "deletes a single pet based on the ID supplied", + operationId: "deletePet", + parameters: [ + { + name: "id", + in: "path", + description: "ID of pet to delete", + required: true, + schema: { + type: "integer", + format: "int64", + }, + }, + ], + responses: { + "204": { + description: "pet deleted", + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + }, + }, + components: { + schemas: { + Pet: { + allOf: [ + { + $ref: "#/components/schemas/NewPet", + }, + { + type: "object", + required: ["id"], + properties: { + id: { + type: "integer", + format: "int64", + }, + }, + }, + ], + }, + NewPet: { + type: "object", + required: ["name"], + properties: { + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + Error: { + type: "object", + required: ["code", "message"], + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + }, + }, + }, + }, +}; diff --git a/tests/3.0/petstore.ts b/tests/3.0/petstore.ts new file mode 100644 index 0000000..edd67f7 --- /dev/null +++ b/tests/3.0/petstore.ts @@ -0,0 +1,179 @@ +import type { Specification } from "../../3.0"; + +const _petstore: Specification = { + openapi: "3.0.0", + info: { + version: "1.0.0", + title: "Swagger Petstore", + license: { + name: "MIT", + }, + }, + servers: [ + { + url: "http://petstore.swagger.io/v1", + }, + ], + paths: { + "/pets": { + get: { + summary: "List all pets", + operationId: "listPets", + tags: ["pets"], + parameters: [ + { + name: "limit", + in: "query", + description: "How many items to return at one time (max 100)", + required: false, + schema: { + type: "integer", + maximum: 100, + format: "int32", + }, + }, + ], + responses: { + "200": { + description: "A paged array of pets", + headers: { + "x-next": { + description: "A link to the next page of responses", + schema: { + type: "string", + }, + }, + }, + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Pets", + }, + }, + }, + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + post: { + summary: "Create a pet", + operationId: "createPets", + tags: ["pets"], + requestBody: { + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Pet", + }, + }, + }, + required: true, + }, + responses: { + "201": { + description: "Null response", + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + }, + "/pets/{petId}": { + get: { + summary: "Info for a specific pet", + operationId: "showPetById", + tags: ["pets"], + parameters: [ + { + name: "petId", + in: "path", + required: true, + description: "The id of the pet to retrieve", + schema: { + type: "string", + }, + }, + ], + responses: { + "200": { + description: "Expected response to a valid request", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Pet", + }, + }, + }, + }, + default: { + description: "unexpected error", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Error", + }, + }, + }, + }, + }, + }, + }, + }, + components: { + schemas: { + Pet: { + type: "object", + required: ["id", "name"], + properties: { + id: { + type: "integer", + format: "int64", + }, + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + Pets: { + type: "array", + maxItems: 100, + items: { + $ref: "#/components/schemas/Pet", + }, + }, + Error: { + type: "object", + required: ["code", "message"], + properties: { + code: { + type: "integer", + format: "int32", + }, + message: { + type: "string", + }, + }, + }, + }, + }, +}; diff --git a/tests/3.0/uspto.ts b/tests/3.0/uspto.ts new file mode 100644 index 0000000..8e65406 --- /dev/null +++ b/tests/3.0/uspto.ts @@ -0,0 +1,257 @@ +import type { Specification } from "../../3.0"; + +const _uspto: Specification = { + openapi: "3.0.1", + servers: [ + { + url: "{scheme}://developer.uspto.gov/ds-api", + variables: { + scheme: { + description: "The Data Set API is accessible via https and http", + enum: ["https", "http"], + default: "https", + }, + }, + }, + ], + info: { + description: + "The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters.", + version: "1.0.0", + title: "USPTO Data Set API", + contact: { + name: "Open Data Portal", + url: "https://developer.uspto.gov", + email: "developer@uspto.gov", + }, + }, + tags: [ + { + name: "metadata", + description: "Find out about the data sets", + }, + { + name: "search", + description: "Search a data set", + }, + ], + paths: { + "/": { + get: { + tags: ["metadata"], + operationId: "list-data-sets", + summary: "List available data sets", + responses: { + "200": { + description: "Returns a list of data sets", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/dataSetList", + }, + example: { + total: 2, + apis: [ + { + apiKey: "oa_citations", + apiVersionNumber: "v1", + apiUrl: + "https://developer.uspto.gov/ds-api/oa_citations/v1/fields", + apiDocumentationUrl: + "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json", + }, + { + apiKey: "cancer_moonshot", + apiVersionNumber: "v1", + apiUrl: + "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields", + apiDocumentationUrl: + "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json", + }, + ], + }, + }, + }, + }, + }, + }, + }, + "/{dataset}/{version}/fields": { + get: { + tags: ["metadata"], + summary: + "Provides the general information about the API and the list of fields that can be used to query the dataset.", + description: + "This GET API returns the list of all the searchable field names that are in the oa_citations. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the syntax options shown below.", + operationId: "list-searchable-fields", + parameters: [ + { + name: "dataset", + in: "path", + description: "Name of the dataset.", + required: true, + example: "oa_citations", + schema: { + type: "string", + }, + }, + { + name: "version", + in: "path", + description: "Version of the dataset.", + required: true, + example: "v1", + schema: { + type: "string", + }, + }, + ], + responses: { + "200": { + description: + "The dataset API for the given version is found and it is accessible to consume.", + content: { + "application/json": { + schema: { + type: "string", + }, + }, + }, + }, + "404": { + description: + "The combination of dataset name and version is not found in the system or it is not published yet to be consumed by public.", + content: { + "application/json": { + schema: { + type: "string", + }, + }, + }, + }, + }, + }, + }, + "/{dataset}/{version}/records": { + post: { + tags: ["search"], + summary: + "Provides search capability for the data set with the given search criteria.", + description: + "This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the Solr/Lucene Syntax. Please refer https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for the query syntax. List of field names that are searchable can be determined using above GET api.", + operationId: "perform-search", + parameters: [ + { + name: "version", + in: "path", + description: "Version of the dataset.", + required: true, + schema: { + type: "string", + default: "v1", + }, + }, + { + name: "dataset", + in: "path", + description: + "Name of the dataset. In this case, the default value is oa_citations", + required: true, + schema: { + type: "string", + default: "oa_citations", + }, + }, + ], + responses: { + "200": { + description: "successful operation", + content: { + "application/json": { + schema: { + type: "array", + items: { + type: "object", + additionalProperties: { + type: "object", + }, + }, + }, + }, + }, + }, + "404": { + description: "No matching record found for the given criteria.", + }, + }, + requestBody: { + content: { + "application/x-www-form-urlencoded": { + schema: { + type: "object", + properties: { + criteria: { + description: + "Uses Lucene Query Syntax in the format of propertyName:value, propertyName:[num1 TO num2] and date range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the response please see the 'docs' element which has the list of record objects. Each record structure would consist of all the fields and their corresponding values.", + type: "string", + default: "*:*", + }, + start: { + description: "Starting record number. Default value is 0.", + type: "integer", + default: 0, + }, + rows: { + description: + "Specify number of rows to be returned. If you run the search with default values, in the response you will see 'numFound' attribute which will tell the number of records available in the dataset.", + type: "integer", + default: 100, + }, + }, + required: ["criteria"], + }, + }, + }, + }, + }, + }, + }, + components: { + schemas: { + dataSetList: { + type: "object", + properties: { + total: { + type: "integer", + }, + apis: { + type: "array", + items: { + type: "object", + properties: { + apiKey: { + type: "string", + description: "To be used as a dataset parameter value", + }, + apiVersionNumber: { + type: "string", + description: "To be used as a version parameter value", + }, + apiUrl: { + type: "string", + format: "uriref", + description: "The URL describing the dataset's fields", + }, + apiDocumentationUrl: { + type: "string", + format: "uriref", + description: "A URL to the API console for each API", + }, + }, + }, + }, + }, + }, + }, + }, +}; diff --git a/tests/3.1/non-oauth-scopes.ts b/tests/3.1/non-oauth-scopes.ts new file mode 100644 index 0000000..5f45023 --- /dev/null +++ b/tests/3.1/non-oauth-scopes.ts @@ -0,0 +1,34 @@ +import type { Specification } from "../../3.1"; + +const _nonOauthScopes: Specification = { + openapi: "3.1.0", + info: { + title: "Non-oAuth Scopes example", + version: "1.0.0", + }, + paths: { + "/users": { + //@ts-expect-error This is an example specification from OpenAPI, + // it seems to intentionally not conform to the specification, + // as its meant to be a minimal example. + get: { + security: [ + { + bearerAuth: ["read:users", "public"], + }, + ], + }, + }, + }, + components: { + securitySchemes: { + bearerAuth: { + type: "http", + scheme: "bearer", + bearerFormat: "jwt", + description: + "note: non-oauth scopes are not defined at the securityScheme level", + }, + }, + }, +}; diff --git a/tests/3.1/tictactoe.ts b/tests/3.1/tictactoe.ts new file mode 100644 index 0000000..2da7bfa --- /dev/null +++ b/tests/3.1/tictactoe.ts @@ -0,0 +1,266 @@ +import type { Specification } from "../../3.1"; + +const _tictactoe: Specification = { + openapi: "3.1.0", + info: { + title: "Tic Tac Toe", + description: + "This API allows writing down marks on a Tic Tac Toe board\nand requesting the state of the board or of individual squares.\n", + version: "1.0.0", + }, + tags: [ + { + name: "Gameplay", + }, + ], + paths: { + "/board": { + get: { + summary: "Get the whole board", + description: "Retrieves the current state of the board and the winner.", + tags: ["Gameplay"], + operationId: "get-board", + responses: { + "200": { + description: "OK", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/status", + }, + }, + }, + }, + }, + security: [ + { + defaultApiKey: [], + }, + { + app2AppOauth: ["board:read"], + }, + ], + }, + }, + "/board/{row}/{column}": { + parameters: [ + { + $ref: "#/components/parameters/rowParam", + }, + { + $ref: "#/components/parameters/columnParam", + }, + ], + get: { + summary: "Get a single board square", + description: "Retrieves the requested square.", + tags: ["Gameplay"], + operationId: "get-square", + responses: { + "200": { + description: "OK", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/mark", + }, + }, + }, + }, + "400": { + description: "The provided parameters are incorrect", + content: { + "text/html": { + schema: { + $ref: "#/components/schemas/errorMessage", + }, + example: "Illegal coordinates", + }, + }, + }, + }, + security: [ + { + bearerHttpAuthentication: [], + }, + { + user2AppOauth: ["board:read"], + }, + ], + }, + put: { + summary: "Set a single board square", + description: + "Places a mark on the board and retrieves the whole board and the winner (if any).", + tags: ["Gameplay"], + operationId: "put-square", + requestBody: { + required: true, + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/mark", + }, + }, + }, + }, + responses: { + "200": { + description: "OK", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/status", + }, + }, + }, + }, + "400": { + description: "The provided parameters are incorrect", + content: { + "text/html": { + schema: { + $ref: "#/components/schemas/errorMessage", + }, + examples: { + illegalCoordinates: { + value: "Illegal coordinates.", + }, + notEmpty: { + value: "Square is not empty.", + }, + invalidMark: { + value: "Invalid Mark (X or O).", + }, + }, + }, + }, + }, + }, + security: [ + { + bearerHttpAuthentication: [], + }, + { + user2AppOauth: ["board:write"], + }, + ], + }, + }, + }, + components: { + parameters: { + rowParam: { + description: "Board row (vertical coordinate)", + name: "row", + in: "path", + required: true, + schema: { + $ref: "#/components/schemas/coordinate", + }, + }, + columnParam: { + description: "Board column (horizontal coordinate)", + name: "column", + in: "path", + required: true, + schema: { + $ref: "#/components/schemas/coordinate", + }, + }, + }, + schemas: { + errorMessage: { + type: "string", + maxLength: 256, + description: "A text message describing an error", + }, + coordinate: { + type: "integer", + minimum: 1, + maximum: 3, + example: 1, + }, + mark: { + type: "string", + enum: [".", "X", "O"], + description: + "Possible values for a board square. `.` means empty square.", + example: ".", + }, + board: { + type: "array", + maxItems: 3, + minItems: 3, + items: { + type: "array", + maxItems: 3, + minItems: 3, + items: { + $ref: "#/components/schemas/mark", + }, + }, + }, + winner: { + type: "string", + enum: [".", "X", "O"], + description: "Winner of the game. `.` means nobody has won yet.", + example: ".", + }, + status: { + type: "object", + properties: { + winner: { + $ref: "#/components/schemas/winner", + }, + board: { + $ref: "#/components/schemas/board", + }, + }, + }, + }, + securitySchemes: { + defaultApiKey: { + description: "API key provided in console", + type: "apiKey", + name: "api-key", + in: "header", + }, + basicHttpAuthentication: { + description: "Basic HTTP Authentication", + type: "http", + scheme: "Basic", + }, + bearerHttpAuthentication: { + description: "Bearer token using a JWT", + type: "http", + scheme: "Bearer", + bearerFormat: "JWT", + }, + app2AppOauth: { + type: "oauth2", + flows: { + clientCredentials: { + tokenUrl: "https://learn.openapis.org/oauth/2.0/token", + scopes: { + "board:read": "Read the board", + }, + }, + }, + }, + user2AppOauth: { + type: "oauth2", + flows: { + authorizationCode: { + authorizationUrl: "https://learn.openapis.org/oauth/2.0/auth", + tokenUrl: "https://learn.openapis.org/oauth/2.0/token", + scopes: { + "board:read": "Read the board", + "board:write": "Write to the board", + }, + }, + }, + }, + }, + }, +}; diff --git a/tests/3.1/webhook-example.ts b/tests/3.1/webhook-example.ts new file mode 100644 index 0000000..00e7164 --- /dev/null +++ b/tests/3.1/webhook-example.ts @@ -0,0 +1,50 @@ +import type { Specification } from "../../3.1"; + +const _webhookExample: Specification = { + openapi: "3.1.0", + info: { + title: "Webhook Example", + version: "1.0.0", + }, + webhooks: { + newPet: { + post: { + requestBody: { + description: "Information about a new pet in the system", + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/Pet", + }, + }, + }, + }, + responses: { + "200": { + description: + "Return a 200 status to indicate that the data was received successfully", + }, + }, + }, + }, + }, + components: { + schemas: { + Pet: { + required: ["id", "name"], + properties: { + id: { + type: "integer", + format: "int64", + }, + name: { + type: "string", + }, + tag: { + type: "string", + }, + }, + }, + }, + }, +}; diff --git a/tsconfig.json b/tsconfig.json index c7bc083..2a931b7 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,30 +1,31 @@ { - "compilerOptions": { - // Environment setup & latest features - "lib": ["ESNext"], - "target": "ESNext", - "module": "Preserve", - "moduleDetection": "force", - "jsx": "react-jsx", - "allowJs": true, + "compilerOptions": { + // Environment setup & latest features + "lib": ["ESNext"], + "target": "ESNext", + "module": "Preserve", + "moduleDetection": "force", + "jsx": "react-jsx", + "allowJs": true, - // Bundler mode - "moduleResolution": "bundler", - "allowImportingTsExtensions": true, - "verbatimModuleSyntax": true, - "noEmit": true, + // Bundler mode + "moduleResolution": "bundler", + "allowImportingTsExtensions": true, + "verbatimModuleSyntax": true, + "noEmit": true, - // Best practices - "strict": true, - "skipLibCheck": true, - "noFallthroughCasesInSwitch": true, - "noUncheckedIndexedAccess": true, - "noImplicitOverride": true, - "esModuleInterop": true, + // Best practices + "strict": true, + "skipLibCheck": true, + "noFallthroughCasesInSwitch": true, + "forceConsistentCasingInFileNames": true, + "noUncheckedIndexedAccess": true, + "noImplicitOverride": true, + "esModuleInterop": true, - // Some stricter flags (disabled by default) - "noUnusedLocals": false, - "noUnusedParameters": false, - "noPropertyAccessFromIndexSignature": false - } + // Some stricter flags (disabled by default) + "noUnusedLocals": false, + "noUnusedParameters": false, + "noPropertyAccessFromIndexSignature": false + } }