+43

packages/spec-types/src/extensions/code-samples.ts

reviewed

··· 1 1 + export type LinguistLanguages = 2 2 + | 'C' 3 3 + | 'C#' 4 4 + | 'C++' 5 5 + | 'CoffeeScript' 6 6 + | 'CSS' 7 7 + | 'Dart' 8 8 + | 'DM' 9 9 + | 'Elixir' 10 10 + | 'Go' 11 11 + | 'Groovy' 12 12 + | 'HTML' 13 13 + | 'Java' 14 14 + | 'JavaScript' 15 15 + | 'Kotlin' 16 16 + | 'Objective-C' 17 17 + | 'Perl' 18 18 + | 'PHP' 19 19 + | 'PowerShell' 20 20 + | 'Python' 21 21 + | 'Ruby' 22 22 + | 'Rust' 23 23 + | 'Scala' 24 24 + | 'Shell' 25 25 + | 'Swift' 26 26 + | 'TypeScript'; 27 27 + 28 28 + export interface CodeSampleObject { 29 29 + /** 30 30 + * Code sample label, for example `Node` or `Python2.7`. 31 31 + * 32 32 + * @default `lang` value 33 33 + */ 34 34 + label?: string; 35 35 + /** 36 36 + * **REQUIRED**. Code sample language. Can be one of the automatically supported languages or any other language identifier of your choice (for custom code samples). 37 37 + */ 38 38 + lang: LinguistLanguages; 39 39 + /** 40 40 + * **REQUIRED**. Code sample source code, or a `$ref` to the file containing the code sample. 41 41 + */ 42 42 + source: string; 43 43 + }

+14

packages/spec-types/src/extensions/enum.ts

reviewed

··· 1 1 + export interface EnumExtensions { 2 2 + /** 3 3 + * `x-enum-descriptions` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator. 4 4 + */ 5 5 + 'x-enum-descriptions'?: Array<string>; 6 6 + /** 7 7 + * `x-enum-varnames` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator. 8 8 + */ 9 9 + 'x-enum-varnames'?: Array<string>; 10 10 + /** 11 11 + * {@link https://github.com/RicoSuter/NSwag NSwag} generates `x-enumNames` field containing custom enum names. 12 12 + */ 13 13 + 'x-enumNames'?: Array<string>; 14 14 + }

-67

packages/spec-types/src/extensions/openapi.ts

reviewed

··· 1 1 - export type LinguistLanguages = 2 2 - | 'C' 3 3 - | 'C#' 4 4 - | 'C++' 5 5 - | 'CoffeeScript' 6 6 - | 'CSS' 7 7 - | 'Dart' 8 8 - | 'DM' 9 9 - | 'Elixir' 10 10 - | 'Go' 11 11 - | 'Groovy' 12 12 - | 'HTML' 13 13 - | 'Java' 14 14 - | 'JavaScript' 15 15 - | 'Kotlin' 16 16 - | 'Objective-C' 17 17 - | 'Perl' 18 18 - | 'PHP' 19 19 - | 'PowerShell' 20 20 - | 'Python' 21 21 - | 'Ruby' 22 22 - | 'Rust' 23 23 - | 'Scala' 24 24 - | 'Shell' 25 25 - | 'Swift' 26 26 - | 'TypeScript'; 27 27 - 28 28 - export interface CodeSampleObject { 29 29 - /** 30 30 - * Code sample label, for example `Node` or `Python2.7`. 31 31 - * 32 32 - * @default `lang` value 33 33 - */ 34 34 - label?: string; 35 35 - /** 36 36 - * **REQUIRED**. Code sample language. Can be one of the automatically supported languages or any other language identifier of your choice (for custom code samples). 37 37 - */ 38 38 - lang: LinguistLanguages; 39 39 - /** 40 40 - * **REQUIRED**. Code sample source code, or a `$ref` to the file containing the code sample. 41 41 - */ 42 42 - source: string; 43 43 - } 44 44 - 45 45 - export interface EnumExtensions { 46 46 - /** 47 47 - * `x-enum-descriptions` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator. 48 48 - */ 49 49 - 'x-enum-descriptions'?: Array<string>; 50 50 - /** 51 51 - * `x-enum-varnames` are {@link https://stackoverflow.com/a/66471626 supported} by OpenAPI Generator. 52 52 - */ 53 53 - 'x-enum-varnames'?: Array<string>; 54 54 - /** 55 55 - * {@link https://github.com/RicoSuter/NSwag NSwag} generates `x-enumNames` field containing custom enum names. 56 56 - */ 57 57 - 'x-enumNames'?: Array<string>; 58 58 - } 59 59 - 60 60 - /** 61 61 - * OpenAPI Specification Extensions. 62 62 - * 63 63 - * See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}. 64 64 - */ 65 65 - export interface OpenAPIExtensions { 66 66 - [extension: `x-${string}`]: unknown; 67 67 - }

+8

packages/spec-types/src/extensions/spec.ts

reviewed

··· 1 1 + /** 2 2 + * Specification Extensions. 3 3 + * 4 4 + * See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}. 5 5 + */ 6 6 + export interface SpecExtensions { 7 7 + [extension: `x-${string}`]: unknown; 8 8 + }

+3 -6

packages/spec-types/src/index.ts

reviewed

··· 1 1 - export type { 2 2 - CodeSampleObject, 3 3 - EnumExtensions, 4 4 - LinguistLanguages, 5 5 - OpenAPIExtensions, 6 6 - } from './extensions/openapi'; 1 1 + export type { CodeSampleObject, LinguistLanguages } from './extensions/code-samples'; 2 2 + export type { EnumExtensions } from './extensions/enum'; 3 3 + export type { SpecExtensions } from './extensions/spec'; 7 4 export type * as JSONSchemaDraft4 from './json-schema/draft-4'; 8 5 export type * as JSONSchemaDraft2020_12 from './json-schema/draft-2020-12'; 9 6 export * as JSONSchema from './json-schema/union';

+1 -12

packages/spec-types/src/json-schema/draft-2020-12/spec.ts

reviewed

··· 1 1 import type { AnyString, MaybeArray } from '@hey-api/types'; 2 2 3 3 - import type { EnumExtensions, OpenAPIExtensions } from '../../extensions/openapi'; 4 4 - import type { OpenAPIV3_1SchemaExtensions } from '../../openapi/v3-1/extensions'; 5 5 - 6 3 // TODO: left out some keywords related to structuring a complex schema and declaring a dialect 7 7 - export interface Document 8 8 - extends 9 9 - ArrayKeywords, 10 10 - NumberKeywords, 11 11 - ObjectKeywords, 12 12 - StringKeywords, 13 13 - EnumExtensions, 14 14 - OpenAPIV3_1SchemaExtensions, 15 15 - OpenAPIExtensions { 4 4 + export interface Document extends ArrayKeywords, NumberKeywords, ObjectKeywords, StringKeywords { 16 5 /** 17 6 * The `$comment` {@link https://json-schema.org/learn/glossary#keyword keyword} is strictly intended for adding comments to a schema. Its value must always be a string. Unlike the annotations `title`, `description`, and `examples`, JSON schema {@link https://json-schema.org/learn/glossary#implementation implementations} aren't allowed to attach any meaning or behavior to it whatsoever, and may even strip them at any time. Therefore, they are useful for leaving notes to future editors of a JSON schema, but should not be used to communicate to users of the schema. 18 7 */

+1 -3

packages/spec-types/src/json-schema/draft-4/spec.ts

reviewed

··· 1 1 import type { AnyString } from '@hey-api/types'; 2 2 3 3 - import type { EnumExtensions } from '../../extensions/openapi'; 4 4 - 5 5 - export interface Document extends EnumExtensions { 3 3 + export interface Document { 6 4 /** 7 5 * A schema can reference another schema using the `$ref` keyword. The value of `$ref` is a URI-reference that is resolved against the schema's {@link https://json-schema.org/understanding-json-schema/structuring#base-uri Base URI}. When evaluating a `$ref`, an implementation uses the resolved identifier to retrieve the referenced schema and applies that schema to the {@link https://json-schema.org/learn/glossary#instance instance}. 8 6 *

+4 -2

packages/spec-types/src/openapi/v2/spec.ts

reviewed

··· 1 1 - import type { CodeSampleObject, EnumExtensions } from '../../extensions/openapi'; 1 1 + import type { CodeSampleObject } from '../../extensions/code-samples'; 2 2 + import type { EnumExtensions } from '../../extensions/enum'; 2 3 import type { Document as JSONSchemaDraft4 } from '../../json-schema/draft-4/spec'; 3 4 import type { OpenAPIV2NullableExtensions } from './extensions'; 4 5 ··· 1306 1307 * - packSize 1307 1308 * ``` 1308 1309 */ 1309 1309 - export interface SchemaObject extends JSONSchemaDraft4, OpenAPIV2NullableExtensions { 1310 1310 + export interface SchemaObject 1311 1311 + extends JSONSchemaDraft4, EnumExtensions, OpenAPIV2NullableExtensions { 1310 1312 /** 1311 1313 * Allows extensions to the Swagger Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#specification-extensions Vendor Extensions} for further details. 1312 1314 */

+34 -28

packages/spec-types/src/openapi/v3-1/spec.ts

reviewed

··· 1 1 - import type { CodeSampleObject, OpenAPIExtensions } from '../../extensions/openapi'; 1 1 + import type { CodeSampleObject } from '../../extensions/code-samples'; 2 2 + import type { EnumExtensions } from '../../extensions/enum'; 3 3 + import type { SpecExtensions } from '../../extensions/spec'; 2 4 import type { Document as JSONSchemaDraft2020_12 } from '../../json-schema/draft-2020-12'; 5 5 + import type { OpenAPIV3_1SchemaExtensions } from './extensions'; 3 6 4 7 /** 5 8 * This is the root object of the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-document OpenAPI document}. 6 9 * 7 10 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}. 8 11 */ 9 9 - export interface Document extends OpenAPIExtensions { 12 12 + export interface Document extends SpecExtensions { 10 13 /** 11 14 * An element to hold various schemas for the document. 12 15 */ ··· 130 133 * description: callback successfully processed 131 134 * ``` 132 135 */ 133 133 - export interface CallbackObject extends OpenAPIExtensions { 136 136 + export interface CallbackObject extends SpecExtensions { 134 137 /** 135 138 * A Path Item Object, or a reference to one, used to define a callback request and expected responses. A {@link https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/callback-example.yaml complete example} is available. 136 139 */ ··· 226 229 * read:pets: read your pets 227 230 * ``` 228 231 */ 229 229 - export interface ComponentsObject extends OpenAPIExtensions { 232 232 + export interface ComponentsObject extends SpecExtensions { 230 233 /** 231 234 * An object to hold reusable {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object Callback Objects}. 232 235 */ ··· 281 284 * email: support@example.com 282 285 * ``` 283 286 */ 284 284 - export interface ContactObject extends OpenAPIExtensions { 287 287 + export interface ContactObject extends SpecExtensions { 285 288 /** 286 289 * The email address of the contact person/organization. This MUST be in the form of an email address. 287 290 */ ··· 422 425 * 423 426 * will map to `Dog` because of the definition in the `mapping` element. 424 427 */ 425 425 - export interface DiscriminatorObject extends OpenAPIExtensions { 428 428 + export interface DiscriminatorObject extends SpecExtensions { 426 429 /** 427 430 * An object to hold mappings between payload values and schema names or references. 428 431 */ ··· 474 477 * type: integer 475 478 * ``` 476 479 */ 477 477 - export interface EncodingObject extends OpenAPIExtensions { 480 480 + export interface EncodingObject extends SpecExtensions { 478 481 /** 479 482 * Determines whether the parameter value SHOULD allow reserved characters, as defined by {@link https://tools.ietf.org/html/rfc3986#section-2.2 RFC3986} `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#encodingContentType `contentType`} (implicit or explicit) SHALL be ignored. 480 483 */ ··· 570 573 * $ref: '#/components/examples/confirmation-success' 571 574 * ``` 572 575 */ 573 573 - export interface ExampleObject extends OpenAPIExtensions { 576 576 + export interface ExampleObject extends SpecExtensions { 574 577 /** 575 578 * Long description for the example. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 576 579 */ ··· 600 603 * url: https://example.com 601 604 * ``` 602 605 */ 603 603 - export interface ExternalDocumentationObject extends OpenAPIExtensions { 606 606 + export interface ExternalDocumentationObject extends SpecExtensions { 604 607 /** 605 608 * A description of the target documentation. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 606 609 */ ··· 648 651 * version: 1.0.1 649 652 * ``` 650 653 */ 651 651 - export interface InfoObject extends OpenAPIExtensions { 654 654 + export interface InfoObject extends SpecExtensions { 652 655 /** 653 656 * The contact information for the exposed API. 654 657 */ ··· 690 693 * identifier: Apache-2.0 691 694 * ``` 692 695 */ 693 693 - export interface LicenseObject extends OpenAPIExtensions { 696 696 + export interface LicenseObject extends SpecExtensions { 694 697 /** 695 698 * An {@link https://spdx.org/licenses/ SPDX} license expression for the API. The `identifier` field is mutually exclusive of the `url` field. 696 699 */ ··· 852 855 * 853 856 * Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. 854 857 */ 855 855 - export interface LinkObject extends OpenAPIExtensions { 858 858 + export interface LinkObject extends SpecExtensions { 856 859 /** 857 860 * A description of the link. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 858 861 */ ··· 912 915 * $ref: "#/components/examples/frog-example" 913 916 * ``` 914 917 */ 915 915 - export interface MediaTypeObject extends OpenAPIExtensions { 918 918 + export interface MediaTypeObject extends SpecExtensions { 916 919 /** 917 920 * A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`. 918 921 */ ··· 954 957 * read:pets: read your pets 955 958 * ``` 956 959 */ 957 957 - export interface OAuthFlowObject extends OpenAPIExtensions { 960 960 + export interface OAuthFlowObject extends SpecExtensions { 958 961 /** 959 962 * **REQUIRED (`"implicit"`, `"authorizationCode"`)**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. 960 963 */ ··· 978 981 * 979 982 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}. 980 983 */ 981 981 - export interface OAuthFlowsObject extends OpenAPIExtensions { 984 984 + export interface OAuthFlowsObject extends SpecExtensions { 982 985 /** 983 986 * Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. 984 987 */ ··· 1046 1049 * - read:pets 1047 1050 * ``` 1048 1051 */ 1049 1049 - export interface OperationObject extends OpenAPIExtensions { 1052 1052 + export interface OperationObject extends SpecExtensions { 1050 1053 /** 1051 1054 * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object Callback Object} that describes a request that may be initiated by the API provider and the expected responses. 1052 1055 */ ··· 1198 1201 * type: number 1199 1202 * ``` 1200 1203 */ 1201 1201 - export interface ParameterObject extends OpenAPIExtensions { 1204 1204 + export interface ParameterObject extends SpecExtensions { 1202 1205 /** 1203 1206 * Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle `style`} is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. 1204 1207 */ ··· 1301 1304 * style: simple 1302 1305 * ``` 1303 1306 */ 1304 1304 - export interface PathItemObject extends OpenAPIExtensions { 1307 1307 + export interface PathItemObject extends SpecExtensions { 1305 1308 /** 1306 1309 * Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-item-object Path Item Object}. In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relative-references-in-uris Relative References}. 1307 1310 */ ··· 1401 1404 * $ref: '#/components/schemas/pet' 1402 1405 * ``` 1403 1406 */ 1404 1404 - export interface PathsObject extends OpenAPIExtensions { 1407 1407 + export interface PathsObject extends SpecExtensions { 1405 1408 /** 1406 1409 * A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-object `Server Object`}'s `url` field in order to construct the full URL. {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating Path templating} is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. 1407 1410 */ ··· 1506 1509 * type: string 1507 1510 * ``` 1508 1511 */ 1509 1509 - export interface RequestBodyObject extends OpenAPIExtensions { 1512 1512 + export interface RequestBodyObject extends SpecExtensions { 1510 1513 /** 1511 1514 * **REQUIRED**. The content of the request body. The key is a media type or {@link https://tools.ietf.org/html/rfc7231#appendix-D media type range} and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* 1512 1515 */ ··· 1582 1585 * description: object created 1583 1586 * ``` 1584 1587 */ 1585 1585 - export interface ResponseObject extends OpenAPIExtensions { 1588 1588 + export interface ResponseObject extends SpecExtensions { 1586 1589 /** 1587 1590 * A map containing descriptions of potential response payloads. The key is a media type or {@link https://datatracker.ietf.org/doc/html/rfc7231#appendix-D media type range} and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* 1588 1591 */ ··· 1630 1633 * $ref: '#/components/schemas/ErrorModel' 1631 1634 * ``` 1632 1635 */ 1633 1633 - export interface ResponsesObject extends OpenAPIExtensions { 1636 1636 + export interface ResponsesObject extends SpecExtensions { 1634 1637 /** 1635 1638 * Any {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#http-status-codes HTTP status code} can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. 1636 1639 */ ··· 1665 1668 * 1666 1669 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}, though as noted, additional properties MAY omit the `x-` prefix within this object. 1667 1670 */ 1668 1668 - export type SchemaObject = JSONSchemaDraft2020_12 & OpenAPIExtensions; 1671 1671 + export type SchemaObject = JSONSchemaDraft2020_12 & 1672 1672 + OpenAPIV3_1SchemaExtensions & 1673 1673 + SpecExtensions & 1674 1674 + EnumExtensions; 1669 1675 1670 1676 /** 1671 1677 * Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsSecuritySchemes Security Schemes} under the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#components-object Components Object}. ··· 1752 1758 * read:pets: read your pets 1753 1759 * ``` 1754 1760 */ 1755 1755 - export type SecuritySchemeObject = OpenAPIExtensions & { 1761 1761 + export type SecuritySchemeObject = SpecExtensions & { 1756 1762 /** 1757 1763 * A description for security scheme. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 1758 1764 */ ··· 1825 1831 * description: Development server 1826 1832 * ``` 1827 1833 */ 1828 1828 - export interface ServerObject extends OpenAPIExtensions { 1834 1834 + export interface ServerObject extends SpecExtensions { 1829 1835 /** 1830 1836 * An optional string describing the host designated by the URL. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 1831 1837 */ ··· 1845 1851 * 1846 1852 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions Specification Extensions}. 1847 1853 */ 1848 1848 - export interface ServerVariableObject extends OpenAPIExtensions { 1854 1854 + export interface ServerVariableObject extends SpecExtensions { 1849 1855 /** 1850 1856 * **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object Schema Object's} treatment of default values, because in those cases parameter values are optional. If the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum `enum`} is defined, the value MUST exist in the enum's values. 1851 1857 */ ··· 1871 1877 * description: Pets operations 1872 1878 * ``` 1873 1879 */ 1874 1874 - export interface TagObject extends OpenAPIExtensions { 1880 1880 + export interface TagObject extends SpecExtensions { 1875 1881 /** 1876 1882 * A description for the tag. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 1877 1883 */ ··· 2078 2084 * </aliens> 2079 2085 * ``` 2080 2086 */ 2081 2081 - export interface XMLObject extends OpenAPIExtensions { 2087 2087 + export interface XMLObject extends SpecExtensions { 2082 2088 /** 2083 2089 * Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. 2084 2090 */

+29 -27

packages/spec-types/src/openapi/v3/spec.ts

reviewed

··· 1 1 - import type { CodeSampleObject, EnumExtensions, OpenAPIExtensions } from '../../extensions/openapi'; 1 1 + import type { CodeSampleObject } from '../../extensions/code-samples'; 2 2 + import type { EnumExtensions } from '../../extensions/enum'; 3 3 + import type { SpecExtensions } from '../../extensions/spec'; 2 4 3 5 /** 4 6 * This is the root object of the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#openapi-description OpenAPI Description}. 5 7 * 6 8 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#specification-extensions Specification Extensions}. 7 9 */ 8 8 - export interface Document extends OpenAPIExtensions { 10 10 + export interface Document extends SpecExtensions { 9 11 /** 10 12 * An element to hold various Objects for the OpenAPI Description. 11 13 */ ··· 47 49 * 48 50 * TODO: examples 49 51 */ 50 50 - export interface CallbackObject extends OpenAPIExtensions { 52 52 + export interface CallbackObject extends SpecExtensions { 51 53 /** 52 54 * A Path Item Object used to define a callback request and expected responses. A {@link https://learn.openapis.org/examples/v3.0/callback-example.html complete example} is available. 53 55 */ ··· 63 65 * 64 66 * TODO: examples 65 67 */ 66 66 - export interface ComponentsObject extends OpenAPIExtensions { 68 68 + export interface ComponentsObject extends SpecExtensions { 67 69 /** 68 70 * An object to hold reusable {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#callback-object Callback Objects}. 69 71 */ ··· 113 115 * email: support@example.com 114 116 * ``` 115 117 */ 116 116 - export interface ContactObject extends OpenAPIExtensions { 118 118 + export interface ContactObject extends SpecExtensions { 117 119 /** 118 120 * The email address of the contact person/organization. This MUST be in the form of an email address. 119 121 */ ··· 160 162 * TODO: default values examples 161 163 * TODO: examples 162 164 */ 163 163 - export interface EncodingObject extends OpenAPIExtensions { 165 165 + export interface EncodingObject extends SpecExtensions { 164 166 /** 165 167 * When this is true, parameter values are serialized using reserved expansion, as defined by {@link https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3 RFC6570}, which allows {@link https://datatracker.ietf.org/doc/html/rfc3986#section-2.2 RFC3986's reserved character set}, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are {@link https://datatracker.ietf.org/doc/html/rfc3986#section-3.4 not allowed in the query string} (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#appendix-c-using-rfc6570-based-serialization C} and {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#appendix-e-percent-encoding-and-form-media-types E} for details. The default value is `false`. This field SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`. 166 168 */ ··· 201 203 * 202 204 * TODO: examples 203 205 */ 204 204 - export interface ExampleObject extends OpenAPIExtensions { 206 206 + export interface ExampleObject extends SpecExtensions { 205 207 /** 206 208 * Long description for the example. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 207 209 */ ··· 232 234 * url: https://example.com 233 235 * ``` 234 236 */ 235 235 - export interface ExternalDocumentationObject extends OpenAPIExtensions { 237 237 + export interface ExternalDocumentationObject extends SpecExtensions { 236 238 /** 237 239 * A description of the target documentation. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 238 240 */ ··· 276 278 * version: 1.0.1 277 279 * ``` 278 280 */ 279 279 - export interface InfoObject extends OpenAPIExtensions { 281 281 + export interface InfoObject extends SpecExtensions { 280 282 /** 281 283 * The contact information for the exposed API. 282 284 */ ··· 313 315 * url: https://www.apache.org/licenses/LICENSE-2.0.html 314 316 * ``` 315 317 */ 316 316 - export interface LicenseObject extends OpenAPIExtensions { 318 318 + export interface LicenseObject extends SpecExtensions { 317 319 /** 318 320 * **REQUIRED**. The license name used for the API. 319 321 */ ··· 339 341 * 340 342 * TODO: examples 341 343 */ 342 342 - export interface LinkObject extends OpenAPIExtensions { 344 344 + export interface LinkObject extends SpecExtensions { 343 345 /** 344 346 * A description of the link. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 345 347 */ ··· 375 377 * 376 378 * TODO: examples 377 379 */ 378 378 - export interface MediaTypeObject extends OpenAPIExtensions { 380 380 + export interface MediaTypeObject extends SpecExtensions { 379 381 /** 380 382 * A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The `encoding` field SHALL only apply to {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#request-body-object Request Body Objects}, and only when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. 381 383 */ ··· 401 403 * 402 404 * TODO: examples 403 405 */ 404 404 - export interface OAuthFlowObject extends OpenAPIExtensions { 406 406 + export interface OAuthFlowObject extends SpecExtensions { 405 407 /** 406 408 * **REQUIRED (`"implicit"`, `"authorizationCode"`)**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. 407 409 */ ··· 425 427 * 426 428 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#specification-extensions Specification Extensions}. 427 429 */ 428 428 - export interface OAuthFlowsObject extends OpenAPIExtensions { 430 430 + export interface OAuthFlowsObject extends SpecExtensions { 429 431 /** 430 432 * Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. 431 433 */ ··· 451 453 * 452 454 * TODO: examples 453 455 */ 454 454 - export interface OperationObject extends OpenAPIExtensions { 456 456 + export interface OperationObject extends SpecExtensions { 455 457 /** 456 458 * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#callback-object Callback Object} that describes a request that may be initiated by the API provider and the expected responses. 457 459 */ ··· 550 552 * 551 553 * TODO: examples 552 554 */ 553 553 - export interface ParameterObject extends OpenAPIExtensions { 555 555 + export interface ParameterObject extends SpecExtensions { 554 556 /** 555 557 * If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-style `style`} is used, and if {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#style-examples behavior is _n/a_ (cannot be serialized)}, the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#schema-object Schema Object} are implementation-defined. This field is valid only for `query` parameters. Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision. 556 558 */ ··· 622 624 * 623 625 * TODO: examples 624 626 */ 625 625 - export interface PathItemObject extends OpenAPIExtensions { 627 627 + export interface PathItemObject extends SpecExtensions { 626 628 /** 627 629 * Allows for a referenced definition of this path item. The value MUST be in the form of a URL, and the referenced structure MUST be in the form of a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-item-object Path Item Object}. In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#relative-references-in-urls Relative References}. 628 630 */ ··· 684 686 * 685 687 * TODO: examples 686 688 */ 687 687 - export interface PathsObject extends OpenAPIExtensions { 689 689 + export interface PathsObject extends SpecExtensions { 688 690 /** 689 691 * A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#server-object Server Object}'s `url` field in order to construct the full URL. {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#path-templating Path templating} is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. 690 692 */ ··· 732 734 * 733 735 * TODO: examples 734 736 */ 735 735 - export interface RequestBodyObject extends OpenAPIExtensions { 737 737 + export interface RequestBodyObject extends SpecExtensions { 736 738 /** 737 739 * **REQUIRED**. The content of the request body. The key is a media type or {@link https://tools.ietf.org/html/rfc7231#appendix-D media type range} and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` 738 740 */ ··· 754 756 * 755 757 * TODO: examples 756 758 */ 757 757 - export interface ResponseObject extends OpenAPIExtensions { 759 759 + export interface ResponseObject extends SpecExtensions { 758 760 /** 759 761 * A map containing descriptions of potential response payloads. The key is a media type or {@link https://tools.ietf.org/html/rfc7231#appendix-D media type range} and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` 760 762 */ ··· 786 788 * 787 789 * TODO: examples 788 790 */ 789 789 - export interface ResponsesObject extends OpenAPIExtensions { 791 791 + export interface ResponsesObject extends SpecExtensions { 790 792 /** 791 793 * Any {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#http-status-codes HTTP status code} can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#reference-object Reference Object} can link to a response that is defined in the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#components-responses OpenAPI Object's `components.responses`} section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `200` and `299`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. 792 794 */ ··· 848 850 * 849 851 * TODO: content, examples 850 852 */ 851 851 - export interface SchemaObject extends EnumExtensions, OpenAPIExtensions { 853 853 + export interface SchemaObject extends EnumExtensions, SpecExtensions { 852 854 /** 853 855 * The value of "additionalProperties" MUST be a boolean or a schema. 854 856 * ··· 1101 1103 * 1102 1104 * TODO: examples 1103 1105 */ 1104 1104 - export type SecuritySchemeObject = OpenAPIExtensions & { 1106 1106 + export type SecuritySchemeObject = SpecExtensions & { 1105 1107 /** 1106 1108 * A description for security scheme. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 1107 1109 */ ··· 1164 1166 * 1165 1167 * TODO: examples 1166 1168 */ 1167 1167 - export interface ServerObject extends OpenAPIExtensions { 1169 1169 + export interface ServerObject extends SpecExtensions { 1168 1170 /** 1169 1171 * An optional string describing the host designated by the URL. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 1170 1172 */ ··· 1184 1186 * 1185 1187 * This object MAY be extended with {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#specification-extensions Specification Extensions}. 1186 1188 */ 1187 1187 - export interface ServerVariableObject extends OpenAPIExtensions { 1189 1189 + export interface ServerVariableObject extends SpecExtensions { 1188 1190 /** 1189 1191 * **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. If the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#server-variable-enum `enum`} is defined, the value SHOULD exist in the enum's values. Note that this behavior is different from the {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#schema-object Schema Object}'s `default` keyword, which documents the receiver's behavior rather than inserting the value into the data. 1190 1192 */ ··· 1211 1213 * description: Pets operations 1212 1214 * ``` 1213 1215 */ 1214 1214 - export interface TagObject extends OpenAPIExtensions { 1216 1216 + export interface TagObject extends SpecExtensions { 1215 1217 /** 1216 1218 * A description for the tag. {@link https://spec.commonmark.org/ CommonMark syntax} MAY be used for rich text representation. 1217 1219 */ ··· 1240 1242 * 1241 1243 * TODO: examples 1242 1244 */ 1243 1243 - export interface XMLObject extends OpenAPIExtensions { 1245 1245 + export interface XMLObject extends SpecExtensions { 1244 1246 /** 1245 1247 * Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. 1246 1248 */