mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
116 lines
3.2 KiB
TypeScript
116 lines
3.2 KiB
TypeScript
/**
|
|
* -----
|
|
* Base Extension Type
|
|
* -----
|
|
*
|
|
* All Swagger objects can be extended with vendor-specific properties.
|
|
* Extension properties MUST begin with "x-" and can have any valid JSON value.
|
|
* This enables API providers to add custom functionality and metadata to their
|
|
* specifications without breaking compatibility with standard Swagger tools.
|
|
*
|
|
* Extensions are a powerful mechanism for adding custom features to API
|
|
* specifications while maintaining interoperability. They allow for:
|
|
* - Custom metadata and annotations
|
|
* - Tool-specific configuration
|
|
* - API versioning information
|
|
* - Custom validation rules
|
|
* - Integration with proprietary systems
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 2.0 | {@link https://swagger.io/specification/v2/#specification-extensions | Swagger 2.0 Specification Extensions} |
|
|
*
|
|
* -----
|
|
* Extension Rules
|
|
* -----
|
|
*
|
|
* @property `x-${string}` - Vendor extensions allow adding custom properties to Swagger objects.
|
|
*
|
|
* @note
|
|
* - All extension property names MUST begin with "x-" followed by any valid identifier
|
|
* - The value can be any valid JSON value (null, primitive, array, or object)
|
|
* - Extensions may or may not be supported by available tooling
|
|
* - Tools can be extended to add support for custom extensions
|
|
* - Extensions should be documented and used consistently within an organization
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (simple extension):
|
|
* ```ts
|
|
* const simpleExtension: Extension = {
|
|
* "x-internal-id": "12345"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (complex extension):
|
|
* ```ts
|
|
* const complexExtension: Extension = {
|
|
* "x-custom-feature": {
|
|
* enabled: true,
|
|
* version: "1.0",
|
|
* configuration: {
|
|
* timeout: 5000,
|
|
* retries: 3
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (array extension):
|
|
* ```ts
|
|
* const arrayExtension: Extension = {
|
|
* "x-tags": ["internal", "beta", "experimental"]
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (boolean extension):
|
|
* ```ts
|
|
* const booleanExtension: Extension = {
|
|
* "x-deprecated": true,
|
|
* "x-experimental": false
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (null extension):
|
|
* ```ts
|
|
* const nullExtension: Extension = {
|
|
* "x-optional-field": null
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (multiple extensions):
|
|
* ```ts
|
|
* const multipleExtensions: Extension = {
|
|
* "x-api-version": "2.1.0",
|
|
* "x-rate-limit": {
|
|
* requests: 1000,
|
|
* window: "1h"
|
|
* },
|
|
* "x-monitoring": {
|
|
* enabled: true,
|
|
* alerts: ["error", "warning"]
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export type Extension = {
|
|
/**
|
|
* Vendor extensions allow adding custom properties to Swagger objects.
|
|
* All extension property names MUST begin with "x-" followed by any valid identifier.
|
|
* The value can be any valid JSON value (null, primitive, array, or object).
|
|
*
|
|
* Extensions enable API providers to add custom functionality and metadata
|
|
* to their specifications without breaking compatibility with standard
|
|
* Swagger tools. They should be used consistently and documented properly.
|
|
*
|
|
* @example { "x-internal-id": "12345" }
|
|
* @example { "x-custom-feature": { enabled: true, version: "1.0" } }
|
|
* @example { "x-tags": ["internal", "beta"] }
|
|
* @example { "x-deprecated": true }
|
|
* @example { "x-optional-field": null }
|
|
*/
|
|
[K in `x-${string}`]: unknown;
|
|
};
|