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
Files
3d0a7a3e3f8b3211ac5c63968920aa454e657974
openapi-types/3.0.x/paths.ts

1207 lines
39 KiB
TypeScript
Raw Blame History

import type { Extension } from "./extensions"
import type { Reference } from "./references"
import type { ExternalDocumentation } from "./external-documentation"
import type { Schema } from "./schema"
import type { Server } from "./servers"
import type { SecurityRequirement } from "./security"
/**
* -----
* Path Item Object
* -----
*
* Describes the operations available on a single path.
* A Path Item MAY be empty, due to ACL constraints.
*
* The Path Item Object describes the operations available on a single path. It can
* contain a summary and description that apply to all operations on the path, as well
* as individual operation definitions for each HTTP method.
*
* | Version | Reference |
* |---|-----|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#path-item-object | OpenAPI 3.0.4 Path Item} |
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#path-item-object | OpenAPI 3.0.3 Path Item} |
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#path-item-object | OpenAPI 3.0.2 Path Item} |
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#path-item-object | OpenAPI 3.0.1 Path Item} |
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#path-item-object | OpenAPI 3.0.0 Path Item} |
*
* -----
* Fields
* -----
*
* @key `$ref` - Optional Allows for an external definition of this path item
* @key `summary` - Optional An optional, string summary, intended to apply to all operations in this path
* @key `description` - Optional An optional, string description, intended to apply to all operations in this path
* @key `get` - Optional A definition of a GET operation on this path
* @key `put` - Optional A definition of a PUT operation on this path
* @key `post` - Optional A definition of a POST operation on this path
* @key `delete` - Optional A definition of a DELETE operation on this path
* @key `options` - Optional A definition of an OPTIONS operation on this path
* @key `head` - Optional A definition of a HEAD operation on this path
* @key `patch` - Optional A definition of a PATCH operation on this path
* @key `trace` - Optional A definition of a TRACE operation on this path
* @key `servers` - Optional An alternative server array to service all operations in this path
* @key `parameters` - Optional A list of parameters that are applicable for all the operations described under this path
* @key `x-${string}` - Specification Extensions
*
* @note
* All operation fields are optional. Parameters can be overridden at the operation level.
* In OpenAPI 3.0.1+, the `servers` property was clarified to allow alternative server
* arrays that override the global servers for operations on this specific path.
*
* -----
* Examples
* -----
*
* @example (simple path item):
* ```ts
* const pathItem: PathItemObject = {
* get: {
* summary: "List users",
* responses: {
* "200": {
* description: "A list of users",
* content: {
* "application/json": {
* schema: { type: "array", items: { $ref: "#/components/schemas/User" } }
* }
* }
* }
* }
* }
* };
* ```
*
* @example (path item with shared parameters):
* ```ts
* const pathItem: PathItemObject = {
* summary: "User management operations",
* parameters: [
* { name: "userId", in: "path", required: true, schema: { type: "string" } }
* ],
* get: { summary: "Get user" },
* put: { summary: "Update user" },
* delete: { summary: "Delete user" }
* };
* ```
*/
export type PathItemObject =
| ({
/**
* Allows for an external definition of this path item. The referenced structure
* MUST be in the format of a Path Item Object.
*/
$ref?: string
/**
* An optional, string summary, intended to apply to all operations in this path.
*
* @example "User management operations"
*/
summary?: string
/**
* An optional, string description, intended to apply to all operations in this path.
* CommonMark syntax MAY be used for rich text representation.
*
* @example "Operations for managing users in the system"
*/
description?: string
/**
* A definition of a GET operation on this path.
*
* @example { summary: "Get users", responses: { "200": { description: "Success" } } }
*/
get?: Operation
/**
* A definition of a PUT operation on this path.
*
* @example { summary: "Update user", responses: { "200": { description: "Success" } } }
*/
put?: Operation
/**
* A definition of a POST operation on this path.
*
* @example { summary: "Create user", responses: { "201": { description: "Created" } } }
*/
post?: Operation
/**
* A definition of a DELETE operation on this path.
*
* @example { summary: "Delete user", responses: { "204": { description: "No Content" } } }
*/
delete?: Operation
/**
* A definition of an OPTIONS operation on this path.
*
* @example { summary: "Get options", responses: { "200": { description: "Options" } } }
*/
options?: Operation
/**
* A definition of a HEAD operation on this path.
*
* @example { summary: "Check if resource exists", responses: { "200": { description: "Exists" } } }
*/
head?: Operation
/**
* A definition of a PATCH operation on this path.
*
* @example { summary: "Partially update user", responses: { "200": { description: "Success" } } }
*/
patch?: Operation
/**
* A definition of a TRACE operation on this path.
*
* @example { summary: "Trace request", responses: { "200": { description: "Success" } } }
*/
trace?: Operation
/**
* An alternative server array to service all operations in this path.
*
* @example [{ url: "https://api.example.com/v1" }]
*/
servers?: Server[]
/**
* A list of parameters that are applicable for all the operations described
* under this path. These parameters can be overridden at the operation level,
* but cannot be removed there. The list MUST NOT include duplicated parameters.
* A unique parameter is defined by a combination of a name and location.
*
* @example [{ name: "limit", in: "query", schema: { type: "integer" } }]
*/
parameters?: Array<Parameter | Reference>
} & Extension)
| Reference
/**
* -----
* Operation Object
* -----
*
* Describes a single API operation on a path.
*
* The Operation Object describes a single API operation on a path. It contains
* information about the operation including its parameters, request body, responses,
* and security requirements.
*
* | Version | Reference |
* |---|-----|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#operation-object | OpenAPI 3.0.4 Operation} |
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#operation-object | OpenAPI 3.0.3 Operation} |
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#operation-object | OpenAPI 3.0.2 Operation} |
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#operation-object | OpenAPI 3.0.1 Operation} |
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#operation-object | OpenAPI 3.0.0 Operation} |
*
* -----
* Fields
* -----
*
* @key `tags` - Optional A list of tags for API documentation control
* @key `summary` - Optional A short summary of what the operation does
* @key `description` - Optional A verbose explanation of the operation behavior
* @key `externalDocs` - Optional Additional external documentation for this operation
* @key `operationId` - Optional Unique string used to identify the operation
* @key `parameters` - Optional A list of parameters that are applicable for this operation
* @key `requestBody` - Optional The request body applicable for this operation
* @key `responses` - Required The list of possible responses as they are returned from executing this operation
* @key `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation
* @key `deprecated` - Optional Declares this operation to be deprecated
* @key `security` - Optional A declaration of which security mechanisms can be used for this operation
* @key `servers` - Optional An alternative server array to service this operation
* @key `x-${string}` - Specification Extensions
*
* @note
* The `responses` field is required and MUST contain at least one response.
* In OpenAPI 3.0.1+, the `operationId` field was clarified to be case-sensitive
* and must be unique across all operations in the API. The `servers` property
* was clarified to allow alternative server arrays that override the global
* servers for this specific operation.
*
* -----
* Examples
* -----
*
* @example (simple operation):
* ```ts
* const operation: Operation = {
* summary: "Get users",
* responses: {
* "200": {
* description: "A list of users",
* content: {
* "application/json": {
* schema: { type: "array", items: { $ref: "#/components/schemas/User" } }
* }
* }
* }
* }
* };
* ```
*
* @example (operation with request body):
* ```ts
* const operation: Operation = {
* summary: "Create user",
* operationId: "createUser",
* requestBody: {
* description: "User data",
* content: {
* "application/json": {
* schema: { $ref: "#/components/schemas/User" }
* }
* }
* },
* responses: {
* "201": {
* description: "User created",
* content: {
* "application/json": {
* schema: { $ref: "#/components/schemas/User" }
* }
* }
* }
* }
* };
* ```
*/
export interface Operation extends Extension {
/**
* A list of tags for API documentation control. Tags can be used for logical
* grouping of operations by resources or any other qualifier.
*
* @example ["users", "authentication"]
* @example ["pets"]
*/
tags?: string[]
/**
* A short summary of what the operation does. For maximum readability in
* OpenAPI-UI, this field SHOULD be less than 120 characters.
*
* @example "Get user by ID"
* @example "Create a new pet"
*/
summary?: string
/**
* A verbose explanation of the operation behavior. CommonMark syntax MAY be used
* for rich text representation.
*
* @example "Retrieves a specific user by their unique identifier. Returns user details including name, email, and profile information."
*/
description?: string
/**
* Additional external documentation for this operation.
*
* @example { description: "Find out more about this operation", url: "https://example.com/docs" }
*/
externalDocs?: ExternalDocumentation
/**
* Unique string used to identify the operation. The id MUST be unique among
* all operations described in the API. Tools and libraries MAY use the
* operationId to uniquely identify an operation, therefore, it is recommended
* to follow common programming naming conventions.
*
* @example "getUserById"
* @example "createPet"
*/
operationId?: string
/**
* A list of parameters that are applicable for this operation. If a parameter
* is already defined at the Path Item, the new definition will override it
* but can never remove it. The list MUST NOT include duplicated parameters.
* A unique parameter is defined by a combination of a name and location.
*
* @example [{ name: "id", in: "path", required: true, schema: { type: "string" } }]
*/
parameters?: Array<Parameter | Reference>
/**
* The request body applicable for this operation. The requestBody is only
* supported in HTTP methods where the HTTP 1.1 specification has explicitly
* defined semantics for request bodies.
*
* @example { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } }
*/
requestBody?: RequestBody | Reference
/**
* The list of possible responses as they are returned from executing this operation.
* This field MUST be present and MUST contain at least one response.
*
* @example { "200": { description: "Success", content: { "application/json": { schema: { type: "object" } } } } }
*/
responses: Record<string, Response | Reference>
/**
* A map of possible out-of band callbacks related to the parent operation.
* The key is a unique identifier for the Callback Object. Each value in the map
* is a Callback Object that describes a request that may be initiated by the API
* provider and the expected responses.
*
* @example { "myCallback": { "{$request.body#/callbackUrl}": { post: { ... } } } }
*/
callbacks?: Record<string, Callback | Reference>
/**
* Declares this operation to be deprecated. Consumers SHOULD refrain from usage
* of the declared operation. Default value is false.
*
* @default false
* @example true
*/
deprecated?: boolean
/**
* A declaration of which security mechanisms can be used for this operation.
* The list of values includes alternative security requirement objects that can be used.
* Only one of the security requirement objects need to be satisfied to authorize a request.
* This definition overrides any declared top-level security.
*
* @example [{ "api_key": [] }]
* @example [{ "oauth2": ["read", "write"] }]
*/
security?: SecurityRequirement[]
/**
* An alternative server array to service this operation. If an alternative
* server object is specified at the Path Item Object or Root level, it will
* be overridden by this value.
*
* @example [{ url: "https://api.example.com/v1" }]
*/
servers?: Server[]
}
/**
* -----
* Parameter Object
* -----
*
* Describes a single operation parameter.
* A unique parameter is defined by a combination of a name and location.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#parameter-object | OpenAPI 3.0.0 Parameter} |
*
* -----
* Fields
* -----
*
* @key `name` - Required The name of the parameter
* @key `in` - Required The location of the parameter
* @key `description` - Optional A brief description of the parameter
* @key `required` - Optional Determines whether this parameter is mandatory
* @key `deprecated` - Optional Specifies that a parameter is deprecated
* @key `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters
* @key `style` - Optional Describes how the parameter value will be serialized
* @key `explode` - Optional When this is true, parameter values generate separate parameters
* @key `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters
* @key `schema` - Optional The schema defining the type used for the parameter
* @key `example` - Optional Example of the media type
* @key `examples` - Optional Examples of the media type
* @key `content` - Optional A map containing the representations for the parameter
* @key `x-${string}` - Specification Extensions
*
* @note
* The `name` and `in` fields are required. A parameter MUST contain either a `schema` property, or a `content` property, but not both.
*
* -----
* Examples
* -----
*
* @example (path parameter):
* ```ts
* const parameter: Parameter = {
* name: "id",
* in: "path",
* required: true,
* description: "User ID",
* schema: { type: "string" }
* };
* ```
*
* @example (query parameter):
* ```ts
* const parameter: Parameter = {
* name: "limit",
* in: "query",
* description: "Number of items to return",
* schema: { type: "integer", minimum: 1, maximum: 100 }
* };
* ```
*/
export interface Parameter extends Extension {
/**
* The name of the parameter. Parameter names are case sensitive.
* - If in is "path", the name field MUST correspond to the associated path segment
* - If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored
* - For all other cases, the name corresponds to the parameter name used by the in property
*
* @example "id"
* @example "limit"
* @example "user"
*/
name: string
/**
* The location of the parameter. Possible values are "query", "header", "path" or "cookie".
*
* - **query**: Parameters that are appended to the URL
* - **header**: Custom headers that are expected as part of the request
* - **path**: Used together with Path Templating, where the parameter value is actually part of the operation's URL
* - **cookie**: Used to pass a specific cookie value to the API
*
* @example "query"
* @example "path"
* @example "header"
* @example "cookie"
*/
in: "query" | "header" | "path" | "cookie"
/**
* A brief description of the parameter. This could contain examples of use.
* CommonMark syntax MAY be used for rich text representation.
*
* @example "User ID to retrieve"
* @example "Number of items to return"
*/
description?: string
/**
* Determines whether this parameter is mandatory. If the parameter location is "path",
* this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be
* included and its default value is false.
*
* @example true
* @example false
*/
required?: boolean
/**
* Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
*
* @example true
* @example false
*/
deprecated?: boolean
/**
* Sets the ability to pass empty-valued parameters. This is valid only for query
* parameters and allows sending a parameter with an empty value. Default value is false.
*
* @example true
* @example false
*/
allowEmptyValue?: boolean
/**
* Describes how the parameter value will be serialized depending on the type of the parameter value.
* Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.
*
* @example "form"
* @example "simple"
* @example "matrix"
* @example "label"
* @example "spaceDelimited"
* @example "pipeDelimited"
* @example "deepObject"
*/
style?: "matrix" | "label" | "form" | "simple" | "spaceDelimited" | "pipeDelimited" | "deepObject"
/**
* When this is true, parameter values of type array or object generate separate parameters
* for each value of the array or key-value pair of the map. For other types of parameters
* this property has no effect. When style is form, the default value is true.
* For all other styles, the default value is false.
*
* @example true
* @example false
*/
explode?: boolean
/**
* Determines whether the parameter value SHOULD allow reserved characters, as defined by
* RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only
* applies to parameters with an in value of query. The default value is false.
*
* @example true
* @example false
*/
allowReserved?: boolean
/**
* The schema defining the type used for the parameter.
*
* @example { type: "string" }
* @example { type: "integer", minimum: 1, maximum: 100 }
*/
schema?: Schema
/**
* Example of the media type. The example SHOULD match the specified schema and encoding
* properties if present. The example object is mutually exclusive of the examples object.
*
* @example "example-value"
* @example 42
*/
example?: unknown
/**
* Examples of the media type. Each example SHOULD contain a value in the correct format
* as specified in the parameter encoding. The examples object is mutually exclusive of
* the example object.
*
* @example { "user1": { summary: "A user example", value: "user123" } }
*/
examples?: Record<string, Example | Reference>
/**
* A map containing the representations for the parameter. The key is the media type
* and the value describes it. The map MUST only contain one entry.
*
* @example { "application/json": { schema: { type: "object" } } }
*/
content?: Record<string, MediaType>
}
/**
* -----
* Request Body Object
* -----
*
* Describes a single request body.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#request-body-object | OpenAPI 3.0.0 Request Body} |
*
* -----
* Fields
* -----
*
* @key `description` - Optional A brief description of the request body
* @key `content` - Required The content of the request body
* @key `required` - Optional Determines if the request body is required in the request
* @key `x-${string}` - Specification Extensions
*
* @note
* The `content` field is required. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification has explicitly defined semantics for request bodies.
*
* -----
* Examples
* -----
*
* @example (simple request body):
* ```ts
* const requestBody: RequestBody = {
* description: "User data",
* content: {
* "application/json": {
* schema: { $ref: "#/components/schemas/User" }
* }
* }
* };
* ```
*/
export interface RequestBody extends Extension {
/**
* A brief description of the request body. This could contain examples of use.
* CommonMark syntax MAY be used for rich text representation.
*
* @example "User data to create"
* @example "Pet information"
*/
description?: string
/**
* The content of the request body. The key is a media type or media type range
* and the value describes it. For requests that match multiple keys, only the
* most specific key is applicable.
*
* @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } }
*/
content: Record<string, MediaType>
/**
* Determines if the request body is required in the request. Defaults to false.
*
* @default false
* @example true
*/
required?: boolean
}
/**
* -----
* Media Type Object
* -----
*
* Each Media Type Object provides schema and examples for the media type identified by its key.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#media-type-object | OpenAPI 3.0.0 Media Type} |
*
* -----
* Fields
* -----
*
* @key `schema` - Optional The schema defining the type used for the request body
* @key `example` - Optional Example of the media type
* @key `examples` - Optional Examples of the media type
* @key `encoding` - Optional A map between a property name and its encoding information
* @key `x-${string}` - Specification Extensions
*
* @note
* The `example` object is mutually exclusive of the `examples` object.
*
* -----
* Examples
* -----
*
* @example (simple media type):
* ```ts
* const mediaType: MediaType = {
* schema: { $ref: "#/components/schemas/User" }
* };
* ```
*/
export interface MediaType extends Extension {
/**
* The schema defining the type used for the request body.
*
* @example { $ref: "#/components/schemas/User" }
* @example { type: "object", properties: { name: { type: "string" } } }
*/
schema?: Schema | Reference
/**
* Example of the media type. The example object SHOULD be in the correct format
* as specified by the media type. The example object is mutually exclusive of
* the examples object.
*
* @example { name: "John Doe", email: "john@example.com" }
*/
example?: unknown
/**
* Examples of the media type. Each example object SHOULD match the media type
* and specified schema if present. The examples object is mutually exclusive of
* the example object.
*
* @example { "user1": { summary: "A user example", value: { name: "John" } } }
*/
examples?: Record<string, Example | Reference>
/**
* A map between a property name and its encoding information. The key, being the
* property name, MUST exist in the schema as a property. The encoding object SHALL
* only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded.
*
* @example { "profileImage": { contentType: "image/png" } }
*/
encoding?: Record<string, Encoding>
}
/**
* -----
* Encoding Object
* -----
*
* A single encoding definition applied to a single schema property.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#encoding-object | OpenAPI 3.0.0 Encoding} |
*
* -----
* Fields
* -----
*
* @key `contentType` - Optional The Content-Type for encoding a specific property
* @key `headers` - Optional A map allowing additional information to be provided as headers
* @key `style` - Optional Describes how a specific property value will be serialized
* @key `explode` - Optional When this is true, property values generate separate parameters
* @key `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters
* @key `x-${string}` - Specification Extensions
*
* @note
* This attribute is only applicable to multipart and application/x-www-form-urlencoded request bodies.
*
* -----
* Examples
* -----
*
* @example (simple encoding):
* ```ts
* const encoding: Encoding = {
* contentType: "image/png"
* };
* ```
*/
export interface Encoding extends Extension {
/**
* The Content-Type for encoding a specific property. Default value depends on the property type.
*
* @example "image/png"
* @example "application/json"
* @example "text/plain"
*/
contentType?: string
/**
* A map allowing additional information to be provided as headers, for example
* Content-Disposition. Content-Type is described separately and SHALL be ignored in this section.
*
* @example { "Content-Disposition": { schema: { type: "string" } } }
*/
headers?: Record<string, Header | Reference>
/**
* Describes how a specific property value will be serialized depending on its type.
* See Parameter Object for details on the style property. The behavior follows the
* same values as query parameters, including default values.
*
* @example "form"
* @example "simple"
*/
style?: "form" | "spaceDelimited" | "pipeDelimited" | "deepObject"
/**
* When this is true, property values of type array or object generate separate parameters
* for each value of the array, or key-value-pair of the map. For other types of properties
* this property has no effect. When style is form, the default value is true.
* For all other styles, the default value is false.
*
* @example true
* @example false
*/
explode?: boolean
/**
* Determines whether the parameter value SHOULD allow reserved characters, as defined by
* RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false.
*
* @example true
* @example false
*/
allowReserved?: boolean
}
/**
* -----
* Response Object
* -----
*
* Describes a single response from an API Operation, including design-time, static
* links to operations based on the response.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#response-object | OpenAPI 3.0.0 Response} |
*
* -----
* Fields
* -----
*
* @key `description` - Required A short description of the response
* @key `headers` - Optional Maps a header name to its definition
* @key `content` - Optional A map containing descriptions of potential response payloads
* @key `links` - Optional A map of operations links that can be followed from the response
* @key `x-${string}` - Specification Extensions
*
* @note
* The `description` field is required.
*
* -----
* Examples
* -----
*
* @example (simple response):
* ```ts
* const response: Response = {
* description: "A list of users",
* content: {
* "application/json": {
* schema: { type: "array", items: { $ref: "#/components/schemas/User" } }
* }
* }
* };
* ```
*/
export interface Response extends Extension {
/**
* A short description of the response. CommonMark syntax MAY be used for rich text representation.
* This field is required.
*
* @example "User successfully retrieved"
* @example "Bad request - invalid input parameters"
* @example "Internal server error"
*/
description: string
/**
* Maps a header name to its definition. RFC7230 states header names are case insensitive.
* If a response header is defined with the name "Content-Type", it SHALL be ignored.
*
* @example { "X-RateLimit-Limit": { schema: { type: "integer" } } }
*/
headers?: Record<string, Header | Reference>
/**
* A map containing descriptions of potential response payloads. The key is a media type
* or media type range and the value describes it. For responses that match multiple keys,
* only the most specific key is applicable.
*
* @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } }
*/
content?: Record<string, MediaType>
/**
* A map of operations links that can be followed from the response. The key of the map
* is a short name for the link, following the naming constraints of the names for Component Objects.
*
* @example { "GetUserByUserId": { operationId: "getUserById", parameters: { userId: "$response.body#/id" } } }
*/
links?: Record<string, Link | Reference>
}
/**
* -----
* Header Object
* -----
*
* The Header Object follows the structure of the Parameter Object with the following changes:
* 1. name MUST NOT be specified, it is given in the corresponding headers map.
* 2. in MUST NOT be specified, it is implicitly in header.
* 3. All traits that are affected by the location MUST be applicable to a location of header.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#header-object | OpenAPI 3.0.0 Header} |
*
* -----
* Examples
* -----
*
* @example (simple header):
* ```ts
* const header: Header = {
* description: "The number of allowed requests in the current period",
* schema: { type: "integer" }
* };
* ```
*/
export interface Header extends Extension {
/**
* A brief description of the header. CommonMark syntax MAY be used for rich text representation.
*
* @example "Rate limit for the current period"
* @example "Content type of the response"
*/
description?: string
/**
* Determines whether this header is mandatory. The property MAY be included and its default value is false.
*
* @example true
* @example false
*/
required?: boolean
/**
* Specifies that a header is deprecated and SHOULD be transitioned out of usage.
*
* @example true
* @example false
*/
deprecated?: boolean
/**
* Sets the ability to pass empty-valued headers. This is valid only for headers
* and allows sending a header with an empty value. Default value is false.
*
* @example true
* @example false
*/
allowEmptyValue?: boolean
/**
* Describes how the header value will be serialized. The default value is simple.
*
* @example "simple"
*/
style?: "simple"
/**
* When this is true, header values of type array or object generate separate headers
* for each value of the array or key-value pair of the map. For other types of headers
* this property has no effect. The default value is false.
*
* @example true
* @example false
*/
explode?: boolean
/**
* The schema defining the type used for the header.
*
* @example { type: "integer" }
* @example { type: "string" }
*/
schema?: Schema | Reference
/**
* Example of the media type. The example SHOULD match the specified schema and encoding
* properties if present. The example object is mutually exclusive of the examples object.
*
* @example "example-value"
* @example 42
*/
example?: unknown
/**
* Examples of the media type. Each example SHOULD contain a value in the correct format
* as specified in the header encoding. The examples object is mutually exclusive of
* the example object.
*
* @example { "header1": { summary: "A header example", value: "value123" } }
*/
examples?: Record<string, Example | Reference>
/**
* A map containing the representations for the header. The key is the media type
* and the value describes it. The map MUST only contain one entry.
*
* @example { "application/json": { schema: { type: "object" } } }
*/
content?: Record<string, MediaType>
}
/**
* -----
* Callback Object
* -----
*
* A map of possible out-of band callbacks related to the parent operation.
* Each value in the map is a Path Item Object that describes a set of requests
* that may be initiated by the API provider and the expected responses.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#callback-object | OpenAPI 3.0.0 Callback} |
*
* -----
* Examples
* -----
*
* @example (simple callback):
* ```ts
* const callback: Callback = {
* "{$request.body#/callbackUrl}": {
* post: {
* requestBody: {
* content: {
* "application/json": {
* schema: { $ref: "#/components/schemas/SomePayload" }
* }
* }
* },
* responses: {
* "200": {
* description: "webhook successfully processed"
* }
* }
* }
* }
* };
* ```
*/
export type Callback = Record<string, PathItemObject>
/**
* -----
* Link Object
* -----
*
* The Link object represents a possible design-time link for a response.
* The presence of a link does not guarantee the caller's ability to successfully invoke it,
* rather it provides a known relationship and traversal mechanism between responses and other operations.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#link-object | OpenAPI 3.0.0 Link} |
*
* -----
* Fields
* -----
*
* @key `operationRef` - Optional A relative or absolute reference to an OAS operation
* @key `operationId` - Optional The name of an existing, resolvable OAS operation
* @key `parameters` - Optional A map representing parameters to pass to an operation
* @key `requestBody` - Optional A literal value or expression to use as a request body
* @key `description` - Optional A description of the link
* @key `server` - Optional A server object to be used by the target operation
* @key `x-${string}` - Specification Extensions
*
* @note
* A linked operation MUST be identified using either an operationRef or operationId.
*
* -----
* Examples
* -----
*
* @example (link with operationId):
* ```ts
* const link: Link = {
* operationId: "getUserById",
* parameters: {
* userId: "$response.body#/id"
* }
* };
* ```
*/
export interface Link extends Extension {
/**
* A relative or absolute reference to an OAS operation. This field is mutually
* exclusive of the operationId field, and MUST point to an Operation Object.
*
* @example "#/paths/~12.0~1repositories~1{username}/get"
* @example "https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get"
*/
operationRef?: string
/**
* The name of an existing, resolvable OAS operation, as defined with a unique operationId.
* This field is mutually exclusive of the operationRef field.
*
* @example "getUserById"
* @example "createPet"
*/
operationId?: string
/**
* A map representing parameters to pass to an operation as specified with operationId
* or identified via operationRef. The key is the parameter name to be used, whereas
* the value can be a constant or an expression to be evaluated and passed to the linked operation.
*
* @example { userId: "$response.body#/id" }
* @example { limit: 10 }
*/
parameters?: Record<string, unknown>
/**
* A literal value or expression to use as a request body when calling the target operation.
*
* @example { name: "John Doe" }
* @example "$request.body#/user"
*/
requestBody?: unknown
/**
* A description of the link. CommonMark syntax MAY be used for rich text representation.
*
* @example "Get user by ID"
* @example "Create a new pet"
*/
description?: string
/**
* A server object to be used by the target operation.
*
* @example { url: "https://api.example.com/v1" }
*/
server?: Server
}
/**
* -----
* Example Object
* -----
*
* In all cases, the example value is expected to be compatible with the type schema
* of its associated value. Tooling implementations MAY choose to validate compatibility
* automatically, and reject the example value(s) if incompatible.
*
* | Version | Reference |
* |---|-----|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#example-object | OpenAPI 3.0.0 Example} |
*
* -----
* Fields
* -----
*
* @key `summary` - Optional Short description for the example
* @key `description` - Optional Long description for the example
* @key `value` - Optional Embedded literal example
* @key `externalValue` - Optional A URL that points to the literal example
* @key `x-${string}` - Specification Extensions
*
* @note
* The `value` field and `externalValue` field are mutually exclusive.
*
* -----
* Examples
* -----
*
* @example (simple example):
* ```ts
* const example: Example = {
* summary: "A user example",
* value: { name: "John Doe", email: "john@example.com" }
* };
* ```
*/
export interface Example extends Extension {
/**
* Short description for the example.
*
* @example "A user example"
* @example "An error response"
*/
summary?: string
/**
* Long description for the example. CommonMark syntax MAY be used for rich text representation.
*
* @example "A complete user object with all fields populated"
* @example "An error response when the user is not found"
*/
description?: string
/**
* Embedded literal example. The value field and externalValue field are mutually exclusive.
* To represent examples of media types that cannot naturally represented in JSON or YAML,
* use a string value to contain the example, escaping where necessary.
*
* @example { name: "John Doe", email: "john@example.com" }
* @example "example string value"
*/
value?: unknown
/**
* A URL that points to the literal example. This provides the capability to reference
* examples that cannot easily be included in JSON or YAML documents. The value field
* and externalValue field are mutually exclusive.
*
* @example "https://example.com/examples/user-example.json"
* @example "https://example.com/examples/error-example.xml"
*/
externalValue?: string
}
Reference in New Issue View Git Blame Copy Permalink