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