mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
351 lines
9.5 KiB
TypeScript
351 lines
9.5 KiB
TypeScript
import type { Extension } from "./extensions";
|
|
|
|
/**
|
|
* -----
|
|
* Info Object
|
|
* -----
|
|
*
|
|
* The object provides metadata about the API. The metadata MAY be used by tooling
|
|
* as required. The object may be extended with Specification Extensions.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `title` - Required The title of the API
|
|
* @property `summary` - Optional A short summary of the API
|
|
* @property `description` - Optional A description of the API
|
|
* @property `termsOfService` - Optional A URL to the Terms of Service for the API
|
|
* @property `contact` - Optional The contact information for the exposed API
|
|
* @property `license` - Optional The license information for the exposed API
|
|
* @property `version` - Required The version of the OpenAPI document
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `title` and `version` fields are required.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (minimal info):
|
|
* ```ts
|
|
* const info: Info = {
|
|
* title: "Pet Store API",
|
|
* version: "1.0.0"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (complete info):
|
|
* ```ts
|
|
* const info: Info = {
|
|
* title: "Pet Store API",
|
|
* summary: "A sample API that uses a petstore as an example",
|
|
* description: "This is a sample server Petstore server.",
|
|
* termsOfService: "http://example.com/terms/",
|
|
* contact: {
|
|
* name: "API Support",
|
|
* url: "http://www.example.com/support",
|
|
* email: "support@example.com"
|
|
* },
|
|
* license: {
|
|
* name: "Apache 2.0",
|
|
* url: "https://www.apache.org/licenses/LICENSE-2.0.html"
|
|
* },
|
|
* version: "1.0.0"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface Info extends Extension {
|
|
/**
|
|
* The title of the API.
|
|
* This field is required and should be descriptive of the API.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - title} |
|
|
*
|
|
* @property `title` - Required The title of the API
|
|
*
|
|
* @example "Pet Store API"
|
|
*/
|
|
title: string;
|
|
|
|
/**
|
|
* A short summary of the API.
|
|
* This should be a brief description of what the API does.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - summary} |
|
|
*
|
|
* @property `summary` - Optional A short summary of the API
|
|
*
|
|
* @example "A sample API that uses a petstore as an example"
|
|
*/
|
|
summary?: string;
|
|
|
|
/**
|
|
* A description of the API.
|
|
* CommonMark syntax MAY be used for rich text representation.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - description} |
|
|
*
|
|
* @property `description` - Optional A description of the API
|
|
*
|
|
* @example "This is a sample server Petstore server."
|
|
*/
|
|
description?: string;
|
|
|
|
/**
|
|
* A URL to the Terms of Service for the API.
|
|
* This MUST be in the format of a URL.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - termsOfService} |
|
|
*
|
|
* @property `termsOfService` - Optional A URL to the Terms of Service for the API
|
|
*
|
|
* @example "http://example.com/terms/"
|
|
*/
|
|
termsOfService?: string;
|
|
|
|
/**
|
|
* The contact information for the exposed API.
|
|
* This object contains contact details for the API.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - contact} |
|
|
*
|
|
* @property `contact` - Optional The contact information for the exposed API
|
|
*
|
|
* @example { name: "API Support", email: "support@example.com" }
|
|
*/
|
|
contact?: Contact;
|
|
|
|
/**
|
|
* The license information for the exposed API.
|
|
* This object contains license details for the API.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - license} |
|
|
*
|
|
* @property `license` - Optional The license information for the exposed API
|
|
*
|
|
* @example { name: "Apache 2.0", url: "https://www.apache.org/licenses/LICENSE-2.0.html" }
|
|
*/
|
|
license?: License;
|
|
|
|
/**
|
|
* The version of the OpenAPI document.
|
|
* This field is required and should follow semantic versioning.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#info-object | OpenAPI 3.2.0 Info Object - version} |
|
|
*
|
|
* @property `version` - Required The version of the OpenAPI document
|
|
*
|
|
* @example "1.0.0"
|
|
*/
|
|
version: string;
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* Contact Object
|
|
* -----
|
|
*
|
|
* The Contact Object provides contact information for the exposed API.
|
|
* It appears in the OpenAPI and Swagger specifications from v2.0 through v3.2.x.
|
|
*
|
|
* Specification Extensions (`x-*`) are always allowed.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `name` - Optional The identifying name of the contact person/organization.
|
|
* @property `url` - Optional A URL pointing to the contact information.
|
|
* @property `email` - Optional The email address of the contact person/organization.
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* All fields are optional.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (full contact object):
|
|
* ```ts
|
|
* const contact: Contact = {
|
|
* name: "API Support",
|
|
* url: "http://www.acme.com/support",
|
|
* email: "support@acme.com"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (just name + email):
|
|
* ```ts
|
|
* const contact: Contact = {
|
|
* name: "Jane Doe",
|
|
* email: "jane.doe@acme.com"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (with extension):
|
|
* ```ts
|
|
* const contact: Contact = {
|
|
* name: "Internal API Team",
|
|
* email: "api-team@acme.com",
|
|
* "x-slack": "#api-support"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface Contact extends Extension {
|
|
/**
|
|
* The identifying name of the contact person/organization.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact Object - name} |
|
|
*
|
|
* @property `name` - Optional The identifying name of the contact person/organization
|
|
*
|
|
* @example "API Support"
|
|
* @example "John Doe"
|
|
*/
|
|
name?: string;
|
|
|
|
/**
|
|
* The URL pointing to the contact information.
|
|
* MUST be in the format of a URL.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact Object - url} |
|
|
*
|
|
* @property `url` - Optional A URL pointing to the contact information
|
|
*
|
|
* @example "http://www.acme.com/support"
|
|
* @example "https://example.com/contact"
|
|
*/
|
|
url?: string;
|
|
|
|
/**
|
|
* The email address of the contact person/organization.
|
|
* MUST be in the format of an email address.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#contact-object | OpenAPI 3.2.0 Contact Object - email} |
|
|
*
|
|
* @property `email` - Optional The email address of the contact person/organization
|
|
*
|
|
* @example "support@acme.com"
|
|
* @example "contact@example.com"
|
|
*/
|
|
email?: string;
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* License Object
|
|
* -----
|
|
*
|
|
* The License Object provides license information for the exposed API.
|
|
* It appears in the OpenAPI and Swagger specifications from v2.0 through v3.2.x.
|
|
*
|
|
* Specification Extensions (`x-*`) are always allowed.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#license-object | OpenAPI 3.2.0 License} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `name` - Required The license name used for the API.
|
|
* @property `url` - Optional A URL to the license used for the API.
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `name` field is required.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (license with name only):
|
|
* ```ts
|
|
* const license: License = {
|
|
* name: "Apache 2.0"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (license with name and URL):
|
|
* ```ts
|
|
* const license: License = {
|
|
* name: "Apache 2.0",
|
|
* url: "https://www.apache.org/licenses/LICENSE-2.0.html"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (license with extension):
|
|
* ```ts
|
|
* const license: License = {
|
|
* name: "MIT",
|
|
* url: "https://opensource.org/licenses/MIT",
|
|
* "x-spdx-id": "MIT"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface License extends Extension {
|
|
/**
|
|
* The license name used for the API.
|
|
* This field is required.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#license-object | OpenAPI 3.2.0 License Object - name} |
|
|
*
|
|
* @property `name` - Required The license name used for the API
|
|
*
|
|
* @example "Apache 2.0"
|
|
* @example "MIT"
|
|
* @example "Proprietary License"
|
|
*/
|
|
name: string;
|
|
|
|
/**
|
|
* A URL to the license used for the API.
|
|
* MUST be in the format of a URL.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.2.0 | {@link https://spec.openapis.org/oas/v3.2.0#license-object | OpenAPI 3.2.0 License Object - url} |
|
|
*
|
|
* @property `url` - Optional A URL to the license used for the API
|
|
*
|
|
* @example "https://www.apache.org/licenses/LICENSE-2.0.html"
|
|
* @example "https://opensource.org/licenses/MIT"
|
|
* @example "https://example.com/licenses/proprietary-1.0"
|
|
*/
|
|
url?: string;
|
|
}
|