mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
86 lines
2.5 KiB
TypeScript
86 lines
2.5 KiB
TypeScript
/**
|
|
* -----
|
|
* Reference Object
|
|
* -----
|
|
*
|
|
* A simple object to allow referencing other components in the specification,
|
|
* internally and externally. The Reference Object is a special JSON object
|
|
* that allows you to reference other parts of the OpenAPI specification.
|
|
*
|
|
* The `$ref` keyword is used to reference other components, and when present,
|
|
* the Reference Object is the only property that should be present (except
|
|
* for `description` and specification extensions).
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#reference-object | OpenAPI 3.1.1 Reference Object} |
|
|
* | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#reference-object | OpenAPI 3.1.0 Reference Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `$ref` - Required The reference string
|
|
* @property `description` - Optional A description of the referenced object
|
|
* @property `summary` - Optional A short summary of the referenced object
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `$ref` field is required and must be a valid JSON Reference.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (internal reference):
|
|
* ```ts
|
|
* const reference: Reference = {
|
|
* "$ref": "#/components/schemas/User"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (external reference):
|
|
* ```ts
|
|
* const reference: Reference = {
|
|
* "$ref": "https://example.com/schemas/User.json"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (reference with description):
|
|
* ```ts
|
|
* const reference: Reference = {
|
|
* "$ref": "#/components/schemas/User",
|
|
* "description": "A user object containing user information"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface Reference {
|
|
/**
|
|
* The reference string. This field is required and must be a valid JSON Reference.
|
|
* It can reference internal components using `#/` or external resources using URLs.
|
|
*
|
|
* @example "#/components/schemas/User"
|
|
* @example "#/components/responses/NotFound"
|
|
* @example "https://example.com/schemas/User.json"
|
|
*/
|
|
$ref: string;
|
|
|
|
/**
|
|
* A description of the referenced object. This can be used to provide
|
|
* additional context about what the referenced object represents.
|
|
*
|
|
* @example "A user object containing user information"
|
|
* @example "Standard error response for not found resources"
|
|
*/
|
|
description?: string;
|
|
|
|
/**
|
|
* A short summary of the referenced object. This can be used to provide
|
|
* a brief overview of what the referenced object represents.
|
|
*
|
|
* @example "User schema"
|
|
* @example "Not found response"
|
|
*/
|
|
summary?: string;
|
|
}
|