openapi-types/2.0/spec.ts

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;