mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 12:37:47 +00:00
133 lines
3.9 KiB
TypeScript
133 lines
3.9 KiB
TypeScript
import type { Extension } from "./extensions";
|
|
|
|
/**
|
|
* -----
|
|
* JSON Reference Object
|
|
* -----
|
|
*
|
|
* A simple object to allow referencing other definitions in the specification.
|
|
* It can be used to reference parameters and responses that are defined at the
|
|
* top level for reuse. The Reference Object is a JSON Reference that uses a
|
|
* JSON Pointer as its value. For this specification, only canonical dereferencing
|
|
* is supported.
|
|
*
|
|
* JSON References enable reusability and modularity in API specifications by
|
|
* allowing the same definition to be referenced multiple times throughout the
|
|
* document. This reduces duplication and makes specifications easier to maintain.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 2.0 | {@link https://swagger.io/specification/v2/#reference-object | Swagger 2.0 Reference Object} |
|
|
* | 2.0 | {@link https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02 | JSON Reference Specification} |
|
|
* | 2.0 | {@link https://tools.ietf.org/html/rfc6901 | JSON Pointer Specification} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `$ref` - The reference string. This field is required.
|
|
*
|
|
* @note
|
|
* The reference string follows JSON Pointer syntax and can reference:
|
|
* - Definitions within the same document using "#/definitions/Name"
|
|
* - Parameters within the same document using "#/parameters/Name"
|
|
* - Responses within the same document using "#/responses/Name"
|
|
* - External files using relative or absolute URLs
|
|
* - Specific parts of external files using fragment identifiers
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (definition reference):
|
|
* ```ts
|
|
* const userRef: BaseReference = {
|
|
* $ref: "#/definitions/User"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (parameter reference):
|
|
* ```ts
|
|
* const pageParamRef: BaseReference = {
|
|
* $ref: "#/parameters/PageParam"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (response reference):
|
|
* ```ts
|
|
* const notFoundRef: BaseReference = {
|
|
* $ref: "#/responses/NotFound"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (external file reference):
|
|
* ```ts
|
|
* const externalRef: BaseReference = {
|
|
* $ref: "Pet.json"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (external file with fragment):
|
|
* ```ts
|
|
* const externalFragmentRef: BaseReference = {
|
|
* $ref: "definitions.json#/Pet"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (absolute URL reference):
|
|
* ```ts
|
|
* const absoluteRef: BaseReference = {
|
|
* $ref: "https://api.example.com/schemas/User.json"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface BaseReference {
|
|
/**
|
|
* The reference string. This field is required.
|
|
*
|
|
* The reference string follows JSON Pointer syntax and can reference:
|
|
* - Definitions within the same document using "#/definitions/Name"
|
|
* - Parameters within the same document using "#/parameters/Name"
|
|
* - Responses within the same document using "#/responses/Name"
|
|
* - External files using relative or absolute URLs
|
|
* - Specific parts of external files using fragment identifiers
|
|
*
|
|
* @example "#/definitions/Pet"
|
|
* @example "#/parameters/skipParam"
|
|
* @example "#/responses/NotFound"
|
|
* @example "Pet.json"
|
|
* @example "definitions.json#/Pet"
|
|
* @example "https://api.example.com/schemas/User.json"
|
|
*/
|
|
$ref: string;
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* Reference Object with Extensions
|
|
* -----
|
|
*
|
|
* A reference object that can be extended with vendor-specific properties.
|
|
* This allows for additional metadata to be attached to references while
|
|
* maintaining the core reference functionality.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 2.0 | {@link https://swagger.io/specification/v2/#reference-object | Swagger 2.0 Reference Object} |
|
|
* | 2.0 | {@link https://swagger.io/specification/v2/#specification-extensions | Swagger 2.0 Extensions} |
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (reference with extensions):
|
|
* ```ts
|
|
* const extendedRef: Reference = {
|
|
* $ref: "#/definitions/User",
|
|
* "x-deprecated": true,
|
|
* "x-version": "1.0.0"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface Reference extends BaseReference, Extension {}
|