mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 12:37:47 +00:00
Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions.
This commit is contained in:
Luke Hagar
236
2.0/spec.ts
Normal file
236
2.0/spec.ts
Normal file
@@ -0,0 +1,236 @@
|
||||
import type { Extension } from "./extensions";
|
||||
import type { ExternalDocumentation } from "./externalDocs";
|
||||
// Import all the major component types
|
||||
import type { Info } from "./info";
|
||||
import type { Paths } from "./paths";
|
||||
import type {
|
||||
Definitions,
|
||||
ParametersDefinitions,
|
||||
ResponsesDefinitions,
|
||||
} from "./schema";
|
||||
import type { SecurityDefinitions, SecurityRequirement } from "./security";
|
||||
import type { Tag } from "./tags";
|
||||
|
||||
/**
|
||||
* Root Swagger 2.0 Schema (Swagger Object)
|
||||
*
|
||||
* This is the root document object of the OpenAPI specification. It contains
|
||||
* all the metadata about the API being described. This object is based on the
|
||||
* JSON Schema Specification Draft 4 and uses a predefined subset of it.
|
||||
*
|
||||
* The Swagger Object is the root of the specification document and contains
|
||||
* all the information about the API, including its metadata, available paths,
|
||||
* data models, security schemes, and more.
|
||||
*
|
||||
* @see https://swagger.io/specification/v2/#swagger-object
|
||||
* @example
|
||||
* ```typescript
|
||||
* const swagger: Specification = {
|
||||
* swagger: "2.0",
|
||||
* info: {
|
||||
* title: "Swagger Sample App",
|
||||
* description: "This is a sample server Petstore server.",
|
||||
* version: "1.0.1"
|
||||
* },
|
||||
* host: "petstore.swagger.io",
|
||||
* basePath: "/v2",
|
||||
* schemes: ["https"],
|
||||
* paths: {
|
||||
* "/pets": {
|
||||
* get: {
|
||||
* summary: "List all pets",
|
||||
* responses: {
|
||||
* "200": {
|
||||
* description: "A list of pets",
|
||||
* schema: {
|
||||
* type: "array",
|
||||
* items: { $ref: "#/definitions/Pet" }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* },
|
||||
* definitions: {
|
||||
* Pet: {
|
||||
* type: "object",
|
||||
* properties: {
|
||||
* id: { type: "integer", format: "int64" },
|
||||
* name: { type: "string" },
|
||||
* tag: { type: "string" }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export type Specification = {
|
||||
/**
|
||||
* Specifies the Swagger specification version being used.
|
||||
* Must be "2.0" for this specification.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - swagger}
|
||||
*/
|
||||
swagger: "2.0";
|
||||
|
||||
/**
|
||||
* Provides metadata about the API. The metadata can be used by the clients
|
||||
* if needed, and can be presented in the Swagger-UI for convenience.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#info-object | Swagger 2.0 Specification - info}
|
||||
*/
|
||||
info: Info;
|
||||
|
||||
/**
|
||||
* The host (name or IP) serving the API. This MUST be the host only and does
|
||||
* not include the scheme nor sub-paths. It MAY include a port. If the host
|
||||
* is not included, the host serving the documentation is to be used
|
||||
* (including the port). The host does not support path templating.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - host}
|
||||
*
|
||||
* @example "api.example.com"
|
||||
* @example "api.example.com:8080"
|
||||
*/
|
||||
host?: string;
|
||||
|
||||
/**
|
||||
* The base path on which the API is served, which is relative to the host.
|
||||
* If it is not included, the API is served directly under the host.
|
||||
* The value MUST start with a leading slash (/). The basePath does not
|
||||
* support path templating.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - basePath}
|
||||
*
|
||||
* @example "/v1"
|
||||
* @example "/api/v2"
|
||||
*/
|
||||
basePath?: string;
|
||||
|
||||
/**
|
||||
* The transfer protocol of the API. Values MUST be from the list:
|
||||
* "http", "https", "ws", "wss". If the schemes is not included, the default
|
||||
* scheme to be used is the one used to access the specification.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - schemes}
|
||||
*
|
||||
* @example ["https", "http"]
|
||||
* @example ["wss"]
|
||||
*/
|
||||
schemes?: Array<"http" | "https" | "ws" | "wss">;
|
||||
|
||||
/**
|
||||
* A list of MIME types the APIs can consume. This is global to all APIs
|
||||
* but can be overridden on specific API calls. Value MUST be as described
|
||||
* under Mime Types.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - consumes}
|
||||
*
|
||||
* @example ["application/json"]
|
||||
* @example ["application/xml", "application/json"]
|
||||
*/
|
||||
consumes?: string[];
|
||||
|
||||
/**
|
||||
* A list of MIME types the APIs can produce. This is global to all APIs
|
||||
* but can be overridden on specific API calls. Value MUST be as described
|
||||
* under Mime Types.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#swagger-object | Swagger 2.0 Specification - produces}
|
||||
*
|
||||
* @example ["application/json"]
|
||||
* @example ["application/xml", "application/json"]
|
||||
*/
|
||||
produces?: string[];
|
||||
|
||||
/**
|
||||
* The available paths and operations for the API. This is the root of the
|
||||
* Path Item Object. It does not define a path or a basePath, they are defined
|
||||
* in the Paths Object. A relative path to an individual endpoint. The field
|
||||
* name MUST begin with a slash. The path is appended to the basePath in order
|
||||
* to construct the full URL. Path templating is allowed.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#paths-object | Swagger 2.0 Specification - paths}
|
||||
*
|
||||
* @example { "/users": { get: { ... } } }
|
||||
* @example { "/users/{id}": { get: { ... } } }
|
||||
*/
|
||||
paths: Paths;
|
||||
|
||||
/**
|
||||
* An object to hold data types produced and consumed by operations.
|
||||
* These data types can be primitives, arrays or models.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#definitions-object | Swagger 2.0 Specification - definitions}
|
||||
*
|
||||
* @example { "User": { type: "object", properties: { ... } } }
|
||||
*/
|
||||
definitions?: Definitions;
|
||||
|
||||
/**
|
||||
* An object to hold parameters that can be used across operations.
|
||||
* This property does not define global parameters for all operations.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#parameters-definitions-object | Swagger 2.0 Specification - parameters}
|
||||
*
|
||||
* @example { "pageParam": { name: "page", in: "query", type: "integer" } }
|
||||
*/
|
||||
parameters?: ParametersDefinitions;
|
||||
|
||||
/**
|
||||
* An object to hold responses that can be used across operations.
|
||||
* This property does not define global responses for all operations.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#responses-definitions-object | Swagger 2.0 Specification - responses}
|
||||
*
|
||||
* @example { "NotFound": { description: "Entity not found" } }
|
||||
*/
|
||||
responses?: ResponsesDefinitions;
|
||||
|
||||
/**
|
||||
* Security scheme definitions that can be used by the operations.
|
||||
* Supported schemes are basic authentication, an API key (either as a header
|
||||
* or as a query parameter) and OAuth2's common flows (implicit, password,
|
||||
* application and access code).
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#security-definitions-object | Swagger 2.0 Specification - securityDefinitions}
|
||||
*
|
||||
* @example { "api_key": { type: "apiKey", in: "header", name: "X-API-Key" } }
|
||||
*/
|
||||
securityDefinitions?: SecurityDefinitions;
|
||||
|
||||
/**
|
||||
* A declaration of which security schemes are applied for the API as a whole.
|
||||
* The list of values describes alternative security schemes that can be used
|
||||
* (that is, there is a logical OR between the security requirements).
|
||||
* Individual operations can override this definition.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#security-requirement-object | Swagger 2.0 Specification - security}
|
||||
*
|
||||
* @example [{ "api_key": [] }]
|
||||
* @example [{ "oauth2": ["read", "write"] }]
|
||||
*/
|
||||
security?: SecurityRequirement[];
|
||||
|
||||
/**
|
||||
* A list of tags used by the specification with additional metadata.
|
||||
* The order of the tags can be used to reflect on their order by the
|
||||
* parsing tools. Not all tags that are used by the Operation Object must
|
||||
* be declared. The tags that are not declared may be organized randomly
|
||||
* or based on the tools' logic. Each tag name in the list MUST be unique.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#tag-object | Swagger 2.0 Specification - tags}
|
||||
*
|
||||
* @example [{ name: "users", description: "User management" }]
|
||||
*/
|
||||
tags?: Tag[];
|
||||
|
||||
/**
|
||||
* Additional external documentation.
|
||||
*
|
||||
* @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - externalDocs}
|
||||
*
|
||||
* @example { description: "Find out more about our API", url: "https://example.com/docs" }
|
||||
*/
|
||||
externalDocs?: ExternalDocumentation;
|
||||
} & Extension;
|
||||
Reference in New Issue
Block a user