LukeParke/openapi-types
1
0
Fork 0
mirror of https://github.com/LukeHagar/openapi-types.git synced 2025-12-06 04:20:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

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.

Browse Source
This commit is contained in:
Luke Hagar
2025-09-25 14:57:24 +00:00
parent 3d0a7a3e3f
commit adc25abc0b
181 changed files with 30313 additions and 14953 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.cursor/rules/jsdoc-formatting.mdc
View File

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

3
.gitignore vendored
View File

@@ -1,6 +1,9 @@
# dependencies (bun install)
node_modules
reports/
# output
out
dist

172
2.0.0/data-types/boolean.ts
View File

@@ -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
}

171
2.0.0/data-types/file.ts
View File

@@ -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
}

14
2.0.0/data-types/index.ts
View File

@@ -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"

234
2.0.0/data-types/integer.ts
View File

@@ -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
}

239
2.0.0/data-types/number.ts
View File

@@ -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
}

205
2.0.0/data-types/object.ts
View File

@@ -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<string, any> // 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
}

107
2.0.0/data-types/schema.ts
View File

@@ -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

215
2.0.0/data-types/string.ts
View File

@@ -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
}

107
2.0.0/index.ts
View File

@@ -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

205
2.0.0/info.ts
View File

@@ -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
}

988
2.0.0/paths.ts
View File

@@ -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<Parameter | BaseReference>
} & 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<Parameter | BaseReference>
/**
* 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<string, Response | BaseReference>
/**
* 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<Record<string, string[]>>
}
/**
* 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<string, PathItemObject>
/**
* 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<string, Header>
/**
* 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<string, unknown>
}
/**
* 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<string, PathItemObject>

378
2.0.0/schema.ts
View File

@@ -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<string, SwaggerSchema | BaseReference>
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<string, SwaggerSchema>
/**
* 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<string, Parameter | BaseReference>
/**
* 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<string, Response | BaseReference>
// Re-export types from paths.ts to avoid circular dependencies
import type { Parameter, Response } from "./paths"

216
2.0.0/security.ts
View File

@@ -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<string, SecurityScheme>

225
2.0.0/spec.ts
View File

@@ -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

142
2.0.0/xml.ts
View File

@@ -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, <books><book/><book/></books>) or unwrapped (<book/><book/>).
* 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
}

0
2.0.0/2.0.md → 2.0/2.0.md
View File

129
2.0.0/data-types/array.ts → 2.0/data-types/array.ts
View File

@@ -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;
}

172
2.0/data-types/boolean.ts Normal file
View File

@@ -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;
}

171
2.0/data-types/file.ts Normal file
View File

@@ -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;
}

10
2.0/data-types/index.ts Normal file
View File

@@ -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";

234
2.0/data-types/integer.ts Normal file
View File

@@ -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;
}

239
2.0/data-types/number.ts Normal file
View File

@@ -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;
}

206
2.0/data-types/object.ts Normal file
View File

@@ -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<string, Schema>; // 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;
}

225
2.0/data-types/string.ts Normal file
View File

@@ -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;
}

30
2.0.0/example.ts → 2.0/example.ts
View File

@@ -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": "<pet><name>Puma</name></pet>" }
* @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": "<pet><name>Puma</name></pet>" }
* @example { "text/plain": "Success" }
*/
[mimeType: string]: unknown;
}

36
2.0.0/extensions.ts → 2.0/extensions.ts
View File

@@ -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;
};

66
2.0.0/externalDocs.ts → 2.0/externalDocs.ts
View File

@@ -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;
}

77
2.0/index.ts Normal file
View File

@@ -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

226
2.0/info.ts Normal file
View File

@@ -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;
}

1220
2.0/paths.ts Normal file
View File

File diff suppressed because it is too large Load Diff

46
2.0.0/references.ts → 2.0/references.ts
View File

@@ -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;
}
/**

316
2.0/schema.ts Normal file
View File

@@ -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<string, Schema>;
/**
* -----
* 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<string, Parameter | BaseReference>;
/**
* -----
* 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<string, Response | BaseReference>;
// Re-export types from paths.ts to avoid circular dependencies
import type { Parameter, Response } from "./paths";

236
2.0/security.ts Normal file
View File

@@ -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<string, SecurityScheme>;

236
2.0/spec.ts Normal file
View File

@@ -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;

935
2.0/status.ts Normal file
View File

@@ -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;
}

96
2.0.0/tags.ts → 2.0/tags.ts
View File

@@ -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;
}

142
2.0/xml.ts Normal file
View File

@@ -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, <books><book/><book/></books>) or unwrapped (<book/><book/>).
* 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;
}

123
3.0.x/components.ts
View File

@@ -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<string, Schema | Reference>
/**
* An object to hold reusable Response Objects.
*
* @example { "NotFound": { description: "Resource not found" } }
*/
responses?: Record<string, any>
/**
* An object to hold reusable Parameter Objects.
*
* @example { "LimitParam": { name: "limit", in: "query", schema: { type: "integer" } } }
*/
parameters?: Record<string, any>
/**
* An object to hold reusable Example Objects.
*
* @example { "UserExample": { summary: "A user example", value: { id: 1, name: "John" } } }
*/
examples?: Record<string, any>
/**
* An object to hold reusable Request Body Objects.
*
* @example { "UserRequest": { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } }
*/
requestBodies?: Record<string, any>
/**
* An object to hold reusable Header Objects.
*
* @example { "RateLimit": { description: "Rate limit header", schema: { type: "integer" } } }
*/
headers?: Record<string, any>
/**
* An object to hold reusable Security Scheme Objects.
*
* @example { "ApiKeyAuth": { type: "apiKey", in: "header", name: "X-API-Key" } }
*/
securitySchemes?: Record<string, any>
/**
* An object to hold reusable Link Objects.
*
* @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } }
*/
links?: Record<string, any>
/**
* An object to hold reusable Callback Objects.
*
* @example { "MyCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { $ref: "#/components/requestBodies/SomeRequestBody" } } } } }
*/
callbacks?: Record<string, any>
}

206
3.0.x/data-types/array.ts
View File

@@ -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
}

165
3.0.x/data-types/boolean.ts
View File

@@ -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
}

207
3.0.x/data-types/composition.ts
View File

@@ -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
}

9
3.0.x/data-types/index.ts
View File

@@ -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"

223
3.0.x/data-types/integer.ts
View File

@@ -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
}

225
3.0.x/data-types/number.ts
View File

@@ -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
}

256
3.0.x/data-types/object.ts
View File

@@ -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<string, any>
/**
* Example value for the schema.
*
* @example { name: "Jane", age: 25 }
* @example { id: 1, title: "Sample" }
*/
example?: Record<string, any>
/**
* Enumeration of valid object values.
*
* @example [{ name: "John" }, { name: "Jane" }]
* @example [{ status: "active" }, { status: "inactive" }]
*/
enum?: Record<string, 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: "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<string, any> // 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<string, any> // 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
}

207
3.0.x/data-types/string.ts
View File

@@ -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
}

57
3.0.x/externalDocs.ts
View File

@@ -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
}

65
3.0.x/index.ts
View File

@@ -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"

295
3.0.x/info.ts
View File

@@ -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
}

1206
3.0.x/paths.ts
View File

File diff suppressed because it is too large Load Diff

49
3.0.x/references.ts
View File

@@ -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
}

225
3.0.x/security.ts
View File

@@ -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<string, string>
}
export interface SecurityRequirement {
[schemeName: string]: string[]
}

197
3.0.x/servers.ts
View File

@@ -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<string, ServerVariable>
}
/**
* -----
* 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
}

200
3.0.x/spec.ts
View File

@@ -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<string, PathItemObject>
/**
* 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

84
3.0.x/tags.ts
View File

@@ -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
}

91
3.0.x/xml.ts
View File

@@ -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,
* <books><book/><book/></books>) or unwrapped (<book/><book/>). Default value is false.
* The definition takes effect only when defined alongside type being array (outside the items).
*
* @example true
* @example false
*/
wrapped?: boolean
}

0
3.0.x/3.0.0.md → 3.0/3.0.0.md
View File

0
3.0.x/3.0.1.md → 3.0/3.0.1.md
View File

0
3.0.x/3.0.2.md → 3.0/3.0.2.md
View File

0
3.0.x/3.0.3.md → 3.0/3.0.3.md
View File

0
3.0.x/3.0.4.md → 3.0/3.0.4.md
View File

214
3.0/components.ts Normal file
View File

@@ -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<string, Schema | Reference>;
/**
* 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<string, Response | Reference>;
/**
* 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<string, Parameter | Reference>;
/**
* 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<string, Example | Reference>;
/**
* 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<string, RequestBody | Reference>;
/**
* 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<string, Header | Reference>;
/**
* 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<string, SecurityScheme | Reference>;
/**
* 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<string, Link | Reference>;
/**
* 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<string, Callback | Reference>;
}

209
3.0/data-types/array.ts Normal file
View File

@@ -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;
}

167
3.0/data-types/boolean.ts Normal file
View File

@@ -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;
}

210
3.0/data-types/composition.ts Normal file
View File

@@ -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;
}

10
3.0/data-types/index.ts Normal file
View File

@@ -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";

225
3.0/data-types/integer.ts Normal file
View File

@@ -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;
}

227
3.0/data-types/number.ts Normal file
View File

@@ -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;
}

259
3.0/data-types/object.ts Normal file
View File

@@ -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<string, unknown>;
/**
* Example value for the schema.
*
* @example { name: "Jane", age: 25 }
* @example { id: 1, title: "Sample" }
*/
example?: Record<string, unknown>;
/**
* Enumeration of valid object values.
*
* @example [{ name: "John" }, { name: "Jane" }]
* @example [{ status: "active" }, { status: "inactive" }]
*/
enum?: Record<string, 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: "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<string, Schema>;
/**
* 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<string, Schema>;
/**
* 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;
}

38
3.0.x/data-types/reference.ts → 3.0/data-types/reference.ts
View File

@@ -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;
}

344
3.0/data-types/string.ts Normal file
View File

@@ -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;
}

6
3.0.x/extensions.ts → 3.0/extensions.ts
View File

@@ -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;
};

75
3.0/externalDocs.ts Normal file
View File

@@ -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;
}

65
3.0/index.ts Normal file
View File

@@ -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";

575
3.0/info.ts Normal file
View File

@@ -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;
}

2039
3.0/paths.ts Normal file
View File

File diff suppressed because it is too large Load Diff

58
3.0/references.ts Normal file
View File

@@ -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;
}

124
3.0.x/schema.ts → 3.0/schema.ts
View File

@@ -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<string, string>
/**
* 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<string, string>;
}
/**
@@ -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.

571
3.0/security.ts Normal file
View File

@@ -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<string, string>;
}
/**
* -----
* 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[];
}

251
3.0/servers.ts Normal file
View File

@@ -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<string, ServerVariable>;
}
/**
* -----
* 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;
}

255
3.0/spec.ts Normal file
View File

@@ -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;

999
3.0/status.ts Normal file
View File

@@ -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;
}

111
3.0/tags.ts Normal file
View File

@@ -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;
}

136
3.0/xml.ts Normal file
View File

@@ -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,
* <books><book/><book/></books>) or unwrapped (<book/><book/>). 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;
}

134
3.1.x/components.ts
View File

@@ -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<string, Schema | Reference>
/**
* An object to hold reusable Response Objects.
*
* @example { NotFound: { description: "Resource not found" } }
*/
responses?: Record<string, Response | Reference>
/**
* An object to hold reusable Parameter Objects.
*
* @example { UserId: { name: "userId", in: "path", required: true, schema: { type: "string" } } }
*/
parameters?: Record<string, Parameter | Reference>
/**
* An object to hold reusable Example Objects.
*
* @example { UserExample: { value: { id: 1, name: "John Doe" } } }
*/
examples?: Record<string, Example | Reference>
/**
* An object to hold reusable Request Body Objects.
*
* @example { UserRequestBody: { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } }
*/
requestBodies?: Record<string, RequestBody | Reference>
/**
* An object to hold reusable Header Objects.
*
* @example { RateLimit: { description: "Rate limit per hour", schema: { type: "integer" } } }
*/
headers?: Record<string, Header | Reference>
/**
* An object to hold reusable Security Scheme Objects.
*
* @example { ApiKeyAuth: { type: "apiKey", in: "header", name: "X-API-KEY" } }
*/
securitySchemes?: Record<string, SecurityScheme | Reference>
/**
* An object to hold reusable Link Objects.
*
* @example { UserOrders: { operationId: "getOrdersByUserId", parameters: { userId: "$response.body#/id" } } }
*/
links?: Record<string, Link | Reference>
/**
* An object to hold reusable Callback Objects.
*
* @example { UserCreatedCallback: { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "User created event" } } } } }
*/
callbacks?: Record<string, Callback | Reference>
/**
* An object to hold reusable Path Item Objects.
*
* @example { UserPath: { get: { summary: "Get user by ID" } } }
*/
pathItems?: Record<string, PathItemObject | Reference>
}

202
3.1.x/data-types/array.ts
View File

@@ -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
}

121
3.1.x/data-types/boolean.ts
View File

@@ -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
}

189
3.1.x/data-types/composition.ts
View File

@@ -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
}

8
3.1.x/data-types/index.ts
View File

@@ -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"

178
3.1.x/data-types/integer.ts
View File

@@ -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
}

178
3.1.x/data-types/number.ts
View File

@@ -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
}

217
3.1.x/data-types/object.ts
View File

@@ -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<string, unknown>
/**
* 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<string, unknown>
/**
* 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<string, string[]>
/**
* 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<string, unknown>
/**
* 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<string, unknown>[]
/**
* A single allowed value for the object.
* The value must be exactly this value.
*
* Example: `{ name: "John" }`
*/
const?: Record<string, unknown>
/**
* An array of example values for the object.
* These are for documentation purposes only.
*
* Example: `[{ name: "John", age: 30 }]`
*/
examples?: Record<string, unknown>[]
/**
* The default value for the object.
* This value will be used if no value is provided.
*
* Example: `{}`
*/
default?: Record<string, unknown>
/**
* 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
}

159
3.1.x/data-types/string.ts
View File

@@ -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
}

263
3.1.x/info.ts
View File

@@ -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
}

1446
3.1.x/paths.ts
View File

File diff suppressed because it is too large Load Diff

255
3.1.x/schema.ts
View File

@@ -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<string, string>
}
/**
* -----
* 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"

358
3.1.x/security.ts
View File

@@ -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<string, string>
}
/**
* -----
* 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[]
}

164
3.1.x/servers.ts
View File

@@ -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<string, ServerVariable>
}
/**
* -----
* 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
}

Some files were not shown because too many files have changed in this diff Show More