mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
120 lines
3.7 KiB
TypeScript
120 lines
3.7 KiB
TypeScript
import type { Extension } from "./extensions";
|
|
|
|
/**
|
|
* -----
|
|
* External Documentation Object
|
|
* -----
|
|
*
|
|
* Allows referencing an external resource for extended documentation.
|
|
* This object provides a way to link to additional documentation that
|
|
* supplements the API specification, such as detailed guides, tutorials,
|
|
* or reference materials.
|
|
*
|
|
* External documentation is commonly used to provide:
|
|
* - Detailed API guides and tutorials
|
|
* - SDK documentation and examples
|
|
* - Integration guides and best practices
|
|
* - Additional reference materials
|
|
* - Community resources and support
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 2.0 | {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 External Documentation Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `description` - A short description of the target documentation. GFM syntax can be used for rich text representation.
|
|
* @property `url` - The URL for the target documentation. Value MUST be in the format of a URL. This field is required.
|
|
*
|
|
* @note
|
|
* The `url` field is required and must be a valid URL. The `description` field
|
|
* is optional but recommended to provide context about the external documentation.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (simple external docs):
|
|
* ```ts
|
|
* const simpleDocs: ExternalDocumentation = {
|
|
* description: "Find more info here",
|
|
* url: "https://swagger.io"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (detailed external docs):
|
|
* ```ts
|
|
* const detailedDocs: ExternalDocumentation = {
|
|
* description: "Complete API documentation with examples and tutorials",
|
|
* url: "https://docs.example.com/api"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (SDK documentation):
|
|
* ```ts
|
|
* const sdkDocs: ExternalDocumentation = {
|
|
* description: "SDK documentation and code examples",
|
|
* url: "https://github.com/example/sdk"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (integration guide):
|
|
* ```ts
|
|
* const integrationDocs: ExternalDocumentation = {
|
|
* description: "Step-by-step integration guide",
|
|
* url: "https://example.com/integration-guide"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (community resources):
|
|
* ```ts
|
|
* const communityDocs: ExternalDocumentation = {
|
|
* description: "Community forum and support resources",
|
|
* url: "https://community.example.com/api-support"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (minimal external docs):
|
|
* ```ts
|
|
* const minimalDocs: ExternalDocumentation = {
|
|
* url: "https://example.com/docs"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface ExternalDocumentation extends Extension {
|
|
/**
|
|
* A short description of the target documentation. GFM syntax can be used for
|
|
* rich text representation.
|
|
*
|
|
* This description provides context about what the external documentation
|
|
* contains and helps developers understand when and why they should
|
|
* reference it.
|
|
*
|
|
* @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - description}
|
|
*
|
|
* @example "Find more info here"
|
|
* @example "Complete API documentation with examples and tutorials"
|
|
* @example "SDK documentation and code examples"
|
|
* @example "Step-by-step integration guide"
|
|
*/
|
|
description?: string;
|
|
|
|
/**
|
|
* The URL for the target documentation. Value MUST be in the format of a URL.
|
|
* This field is required.
|
|
*
|
|
* The URL should point to a valid, accessible resource that provides
|
|
* additional documentation about the API or specific aspects of it.
|
|
*
|
|
* @see {@link https://swagger.io/specification/v2/#external-documentation-object | Swagger 2.0 Specification - url}
|
|
*
|
|
* @example "https://swagger.io"
|
|
* @example "https://docs.example.com/api"
|
|
* @example "https://github.com/example/sdk"
|
|
* @example "https://example.com/integration-guide"
|
|
*/
|
|
url: string;
|
|
}
|