mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
76 lines
3.6 KiB
TypeScript
76 lines
3.6 KiB
TypeScript
import type { Extension } from "./extensions";
|
|
|
|
/**
|
|
* -----
|
|
* External Documentation Object
|
|
* -----
|
|
*
|
|
* Allows referencing an external resource for extended documentation.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `description` - Optional A short description of the target documentation
|
|
* @property `url` - Required The URL for the target documentation
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `url` field is required.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (simple external docs):
|
|
* ```ts
|
|
* const externalDocs: ExternalDocumentation = {
|
|
* description: "Find more info here",
|
|
* url: "https://example.com/docs"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface ExternalDocumentation extends Extension {
|
|
/**
|
|
* A short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation Object - description} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation Object - description} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation Object - description} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation Object - description} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation Object - description} |
|
|
* @property `description` - Optional A short description of the target documentation
|
|
*
|
|
* @example "Find more info here"
|
|
* @example "Additional documentation for this API"
|
|
*/
|
|
description?: string;
|
|
|
|
/**
|
|
* The URL for the target documentation. MUST be in the format of a URL.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#external-documentation-object | OpenAPI 3.0.4 External Documentation Object - url} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#external-documentation-object | OpenAPI 3.0.3 External Documentation Object - url} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#external-documentation-object | OpenAPI 3.0.2 External Documentation Object - url} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#external-documentation-object | OpenAPI 3.0.1 External Documentation Object - url} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#external-documentation-object | OpenAPI 3.0.0 External Documentation Object - url} |
|
|
* @property `url` - Required The URL for the target documentation
|
|
*
|
|
* @example "https://example.com/docs"
|
|
* @example "https://api.example.com/documentation"
|
|
*/
|
|
url: string;
|
|
}
|