mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
215 lines
11 KiB
TypeScript
215 lines
11 KiB
TypeScript
import type { Extension } from "./extensions";
|
|
import type {
|
|
Callback,
|
|
Example,
|
|
Header,
|
|
Link,
|
|
Parameter,
|
|
RequestBody,
|
|
Response,
|
|
} from "./paths";
|
|
import type { Reference } from "./references";
|
|
import type { Schema } from "./schema";
|
|
import type { SecurityScheme } from "./security";
|
|
|
|
/**
|
|
* -----
|
|
* Components Object
|
|
* -----
|
|
*
|
|
* Holds a set of reusable objects for different aspects of the OAS. All objects defined
|
|
* within the components object will have no effect on the API unless they are explicitly
|
|
* referenced from properties outside the components object.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object} |
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `schemas` - An object to hold reusable Schema Objects
|
|
* @property `responses` - An object to hold reusable Response Objects
|
|
* @property `parameters` - An object to hold reusable Parameter Objects
|
|
* @property `examples` - An object to hold reusable Example Objects
|
|
* @property `requestBodies` - An object to hold reusable Request Body Objects
|
|
* @property `headers` - An object to hold reusable Header Objects
|
|
* @property `securitySchemes` - An object to hold reusable Security Scheme Objects
|
|
* @property `links` - An object to hold reusable Link Objects
|
|
* @property `callbacks` - An object to hold reusable Callback Objects
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* All objects defined within the components object will have no effect on the API unless
|
|
* they are explicitly referenced from properties outside the components object.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (basic components):
|
|
* ```ts
|
|
* const components: Components = {
|
|
* schemas: {
|
|
* User: {
|
|
* type: "object",
|
|
* properties: {
|
|
* id: { type: "integer" },
|
|
* name: { type: "string" }
|
|
* }
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface Components extends Extension {
|
|
/**
|
|
* An object to hold reusable Schema Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - schemas} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - schemas} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - schemas} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - schemas} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - schemas} |
|
|
* @property `schemas` - Optional An object to hold reusable Schema Objects
|
|
*
|
|
* @example { "User": { type: "object", properties: { id: { type: "integer" } } } }
|
|
*/
|
|
schemas?: Record<string, Schema | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Response Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - responses} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - responses} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - responses} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - responses} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - responses} |
|
|
* @property `responses` - Optional An object to hold reusable Response Objects
|
|
*
|
|
* @example { "NotFound": { description: "Resource not found" } }
|
|
*/
|
|
responses?: Record<string, Response | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Parameter Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - parameters} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - parameters} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - parameters} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - parameters} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - parameters} |
|
|
* @property `parameters` - Optional An object to hold reusable Parameter Objects
|
|
*
|
|
* @example { "LimitParam": { name: "limit", in: "query", schema: { type: "integer" } } }
|
|
*/
|
|
parameters?: Record<string, Parameter | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Example Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - examples} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - examples} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - examples} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - examples} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - examples} |
|
|
* @property `examples` - Optional An object to hold reusable Example Objects
|
|
*
|
|
* @example { "UserExample": { summary: "A user example", value: { id: 1, name: "John" } } }
|
|
*/
|
|
examples?: Record<string, Example | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Request Body Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - requestBodies} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - requestBodies} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - requestBodies} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - requestBodies} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - requestBodies} |
|
|
* @property `requestBodies` - Optional An object to hold reusable Request Body Objects
|
|
*
|
|
* @example { "UserRequest": { description: "User data", content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } }
|
|
*/
|
|
requestBodies?: Record<string, RequestBody | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Header Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - headers} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - headers} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - headers} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - headers} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - headers} |
|
|
* @property `headers` - Optional An object to hold reusable Header Objects
|
|
*
|
|
* @example { "RateLimit": { description: "Rate limit header", schema: { type: "integer" } } }
|
|
*/
|
|
headers?: Record<string, Header | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Security Scheme Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - securitySchemes} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - securitySchemes} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - securitySchemes} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - securitySchemes} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - securitySchemes} |
|
|
* @property `securitySchemes` - Optional An object to hold reusable Security Scheme Objects
|
|
*
|
|
* @example { "ApiKeyAuth": { type: "apiKey", in: "header", name: "X-API-Key" } }
|
|
*/
|
|
securitySchemes?: Record<string, SecurityScheme | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Link Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - links} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - links} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - links} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - links} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - links} |
|
|
* @property `links` - Optional An object to hold reusable Link Objects
|
|
*
|
|
* @example { "UserRepositories": { operationId: "getUserRepositories", parameters: { username: "$response.body#/username" } } }
|
|
*/
|
|
links?: Record<string, Link | Reference>;
|
|
|
|
/**
|
|
* An object to hold reusable Callback Objects.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#components-object | OpenAPI 3.0.4 Components Object - callbacks} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#components-object | OpenAPI 3.0.3 Components Object - callbacks} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#components-object | OpenAPI 3.0.2 Components Object - callbacks} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#components-object | OpenAPI 3.0.1 Components Object - callbacks} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#components-object | OpenAPI 3.0.0 Components Object - callbacks} |
|
|
* @property `callbacks` - Optional An object to hold reusable Callback Objects
|
|
*
|
|
* @example { "MyCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { $ref: "#/components/requestBodies/SomeRequestBody" } } } } }
|
|
*/
|
|
callbacks?: Record<string, Callback | Reference>;
|
|
}
|