@goast/core 0.7.0-beta.2 → 0.7.1

package/dist/src/codegen/services-generator.js

@@ -1,5 +1,16 @@
 import { OpenApiGenerationProviderBase } from './generator.js';
 import { addSourceIfTest } from './internal-utils.js';
+/**
+ * Base class for generation providers that produce one result per API service.
+ * Results are cached per service. Subclasses implement `initResult`, `generateService` and `addServiceResult`, and can
+ * override `generateAdditionalFiles` to produce output after all services have been processed.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TServiceOutput The type of the result produced for each service.
+ * @template TContext The type of the context that is passed to the provider methods.
+ * @see OpenApiGenerationProviderBase
+ */
 export class OpenApiServicesGenerationProviderBase extends OpenApiGenerationProviderBase {
     getProviderContext(context, config, defaultConfig) {
         const ctx = super.getProviderContext(context, config, defaultConfig);

package/dist/src/codegen/types.d.ts

@@ -1,18 +1,74 @@
 import type { ApiData } from '../transform/api-types.ts';
 import type { MaybePromise } from '../utils/type.utils.ts';
 import type { OpenApiGeneratorConfig } from './config.ts';
+/**
+ * A loosely typed configuration object passed to generation providers, which narrow it to their own options.
+ */
 export type AnyConfig = Readonly<Record<string, unknown>>;
+/**
+ * The merged output of the generation providers that ran before, keyed by the properties they returned.
+ */
 export type OpenApiGeneratorInput = Record<string, unknown>;
+/**
+ * The result of a generation provider. Its properties are deep-merged into the input of the following providers.
+ * A falsy result (`undefined`) is ignored.
+ */
 export type OpenApiGeneratorOutput = Record<string, unknown> | undefined;
+/**
+ * The context that is passed to every generation provider.
+ * @template TInput The type of the merged output of the providers that ran before.
+ */
 export type OpenApiGeneratorContext<TInput extends OpenApiGeneratorInput = OpenApiGeneratorInput> = {
+    /**
+     * The parsed and transformed data of all OpenAPI specifications.
+     */
     data: ApiData;
+    /**
+     * The merged output of the providers that ran before the current one. It is empty for the first provider.
+     */
     input: TInput;
+    /**
+     * The configuration of the generator.
+     */
     config: OpenApiGeneratorConfig;
 };
+/**
+ * The context that is passed to a provider built on `OpenApiGenerationProviderBase`.
+ * It is the same as `OpenApiGeneratorContext`, except that its `config` also contains the provider-specific options.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TConfig The type of the provider-specific configuration.
+ * @see OpenApiGeneratorContext
+ */
 export type OpenApiGenerationProviderContext<TInput extends OpenApiGeneratorInput, TConfig extends AnyConfig> = Omit<OpenApiGeneratorContext<TInput>, 'config'> & {
+    /**
+     * The generator configuration merged with the provider-specific configuration.
+     */
     config: OpenApiGeneratorConfig & TConfig;
 };
+/**
+ * A generation provider implemented as an object with a `generate` method.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by this provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @see OpenApiGenerationProviderFn
+ */
 export interface OpenApiGenerationProvider<TInput extends OpenApiGeneratorInput = OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput = OpenApiGeneratorOutput, TConfig extends AnyConfig = AnyConfig> {
+    /**
+     * Generates the output of this provider.
+     * @param context The context of the generator, including the output of the providers that ran before.
+     * @param config The provider-specific configuration, if any.
+     * @returns The output of this provider, or a promise that resolves to it.
+     */
     generate(...args: Parameters<OpenApiGenerationProviderFn<TInput, TOutput, TConfig>>): ReturnType<OpenApiGenerationProviderFn<TInput, TOutput, TConfig>>;
 }
+/**
+ * A generation provider implemented as a function. Its return value is merged into the input of the following
+ * providers.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by this provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @param context The context of the generator, including the output of the providers that ran before.
+ * @param config The provider-specific configuration, if any.
+ * @returns The output of this provider, or a promise that resolves to it.
+ */
 export type OpenApiGenerationProviderFn<TInput extends OpenApiGeneratorInput = OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput = OpenApiGeneratorOutput, TConfig extends AnyConfig = AnyConfig> = (context: OpenApiGeneratorContext<TInput>, config?: Partial<TConfig>) => MaybePromise<TOutput>;

package/dist/src/collect/collector.d.ts

@@ -1,4 +1,12 @@
 import type { OpenApiDocument } from '../parse/openapi-types.ts';
 import type { Deref } from '../parse/types.ts';
 import type { OpenApiCollectorData } from './types.ts';
+/**
+ * Collects the documents, schemas and endpoints of the given OpenAPI documents into one data object.
+ * Schemas are collected from the components, definitions, parameters, request bodies, responses and headers, including
+ * all nested schemas. Schemas and endpoints are keyed by their source location, so each one is collected only once.
+ * Objects marked with `x-ignore` are skipped.
+ * @param apis The parsed OpenAPI documents to collect from.
+ * @returns The collected documents, schemas and endpoints.
+ */
 export declare function collectOpenApi(apis: Deref<OpenApiDocument>[]): OpenApiCollectorData;

package/dist/src/collect/collector.js

@@ -1,4 +1,12 @@
 import { collect, collectRecord } from './helpers.js';
+/**
+ * Collects the documents, schemas and endpoints of the given OpenAPI documents into one data object.
+ * Schemas are collected from the components, definitions, parameters, request bodies, responses and headers, including
+ * all nested schemas. Schemas and endpoints are keyed by their source location, so each one is collected only once.
+ * Objects marked with `x-ignore` are skipped.
+ * @param apis The parsed OpenAPI documents to collect from.
+ * @returns The collected documents, schemas and endpoints.
+ */
 export function collectOpenApi(apis) {
     const data = {
         documents: [],

package/dist/src/collect/helpers.d.ts

@@ -1,4 +1,20 @@
 import type { Nullable } from '../utils/type.utils.ts';
 import type { OpenApiCollectorData } from './types.ts';
+/**
+ * Calls `func` for each object in a value that is either a single object or an array of objects.
+ * Null entries and objects marked with `x-ignore` are skipped.
+ * @template T The type of the objects.
+ * @param data The collector data that is passed on to `func`.
+ * @param obj The single object or array of objects to visit.
+ * @param func The function that is called for each object.
+ */
 export declare function collect<T extends Record<`x-${string}`, unknown>>(data: OpenApiCollectorData, obj: Nullable<T | Nullable<T>[]>, func: (data: OpenApiCollectorData, obj: NonNullable<T>) => void): void;
+/**
+ * Calls `func` for each value of a record, such as the schemas of a document or the paths of a specification.
+ * Keys starting with `$` or `x-`, null values and values marked with `x-ignore` are skipped.
+ * @template T The type of the values.
+ * @param data The collector data that is passed on to `func`.
+ * @param obj The record to visit.
+ * @param func The function that is called for each value together with its key.
+ */
 export declare function collectRecord<T extends Record<`x-${string}`, unknown>>(data: OpenApiCollectorData, obj: Nullable<Record<string, Nullable<T>>>, func: (data: OpenApiCollectorData, obj: NonNullable<T>, key: string) => void): void;

package/dist/src/collect/helpers.js

@@ -1,4 +1,12 @@
 import { isOpenApiObjectProperty } from '../internal-utils.js';
+/**
+ * Calls `func` for each object in a value that is either a single object or an array of objects.
+ * Null entries and objects marked with `x-ignore` are skipped.
+ * @template T The type of the objects.
+ * @param data The collector data that is passed on to `func`.
+ * @param obj The single object or array of objects to visit.
+ * @param func The function that is called for each object.
+ */
 export function collect(data, obj, func) {
     if (!obj)
         return;
@@ -17,6 +25,14 @@ export function collect(data, obj, func) {
         func(data, obj);
     }
 }
+/**
+ * Calls `func` for each value of a record, such as the schemas of a document or the paths of a specification.
+ * Keys starting with `$` or `x-`, null values and values marked with `x-ignore` are skipped.
+ * @template T The type of the values.
+ * @param data The collector data that is passed on to `func`.
+ * @param obj The record to visit.
+ * @param func The function that is called for each value together with its key.
+ */
 export function collectRecord(data, obj, func) {
     if (!obj)
         return;

package/dist/src/collect/types.d.ts

@@ -1,13 +1,41 @@
 import type { OpenApiDocument, OpenApiHttpMethod, OpenApiOperation, OpenApiPathItem, OpenApiSchema } from '../parse/openapi-types.ts';
 import type { Deref } from '../parse/types.ts';
+/**
+ * Information about an endpoint that was collected from an OpenAPI document.
+ */
 export type OpenApiCollectorEndpointInfo = {
+    /**
+     * The path template of the endpoint, such as `/pets/{id}`.
+     */
     path: string;
+    /**
+     * The HTTP method of the operation.
+     */
     method: OpenApiHttpMethod;
+    /**
+     * The path item that contains the operation.
+     */
     pathItem: Deref<OpenApiPathItem>;
+    /**
+     * The operation that describes the endpoint.
+     */
     operation: Deref<OpenApiOperation>;
 };
+/**
+ * The data that is collected from the OpenAPI documents.
+ * @see collectOpenApi
+ */
 export type OpenApiCollectorData = {
+    /**
+     * The collected OpenAPI documents.
+     */
     documents: Deref<OpenApiDocument>[];
+    /**
+     * The collected schemas, keyed by their source location (`file#path`).
+     */
     schemas: Map<string, Deref<OpenApiSchema>>;
+    /**
+     * The collected endpoints, keyed by the source location (`file#path`) of their operation.
+     */
     endpoints: Map<string, OpenApiCollectorEndpointInfo>;
 };

package/dist/src/internal-utils.d.ts

@@ -1 +1,8 @@
+/**
+ * Checks whether a property name of an OpenAPI object is a regular property. Names starting with `$` (such as `$ref`)
+ * and specification extensions starting with `x-` are not regular properties and should be skipped.
+ * @template T The type of the property name.
+ * @param propertyName The property name to check.
+ * @returns `true` if the name is a regular property name; otherwise, `false`.
+ */
 export declare function isOpenApiObjectProperty<T extends string>(propertyName: T): propertyName is Exclude<T, `$${string}` | `x-${string}`>;

package/dist/src/internal-utils.js

@@ -1,3 +1,10 @@
+/**
+ * Checks whether a property name of an OpenAPI object is a regular property. Names starting with `$` (such as `$ref`)
+ * and specification extensions starting with `x-` are not regular properties and should be skipped.
+ * @template T The type of the property name.
+ * @param propertyName The property name to check.
+ * @returns `true` if the name is a regular property name; otherwise, `false`.
+ */
 export function isOpenApiObjectProperty(propertyName) {
     return !propertyName.startsWith('$') && !propertyName.startsWith('x-');
 }

package/dist/src/parse/deref-proxy.d.ts

@@ -1,3 +1,22 @@
 import type { OpenApiObject } from './openapi-types.ts';
 import type { Deref, DerefSource } from './types.ts';
+/**
+ * Wraps a raw OpenAPI object in a proxy so that `$ref` references are followed transparently.
+ *
+ * Property reads go to the wrapped object first. If it does not define the property, the read falls through to the
+ * resolved `$ref` target, which is looked up at access time. Consumers can therefore read `schema.properties` on a
+ * referencing object without checking whether the value is local or referenced. `title` is the exception and is never
+ * inherited from the target. Assignments are stored on the proxy and do not modify `obj`. The `$ref` and `$src`
+ * properties are always answered by the proxy itself.
+ *
+ * The parser attaches the resolved target as `$ref` while it dereferences a document. The result is typed as
+ * `Deref<T>`, which has the shape of `T` without the raw `$ref` key, plus `$ref` and `$src`.
+ * @template T The raw OpenAPI object type being wrapped.
+ * @param obj The raw object to wrap. It is not modified.
+ * @param source Provenance information, returned by the `$src` property.
+ * @param ref The resolved target of the object's `$ref`, if it has one.
+ * @returns A proxy that behaves like `obj` and follows its reference.
+ * @see Deref
+ * @see DerefSource
+ */
 export declare function createDerefProxy<T extends OpenApiObject<string>>(obj: T, source: DerefSource<T>, ref?: Deref<T>): Deref<T>;

package/dist/src/parse/deref-proxy.js

@@ -1,4 +1,23 @@
 import { isNullish } from '../utils/common.utils.js';
+/**
+ * Wraps a raw OpenAPI object in a proxy so that `$ref` references are followed transparently.
+ *
+ * Property reads go to the wrapped object first. If it does not define the property, the read falls through to the
+ * resolved `$ref` target, which is looked up at access time. Consumers can therefore read `schema.properties` on a
+ * referencing object without checking whether the value is local or referenced. `title` is the exception and is never
+ * inherited from the target. Assignments are stored on the proxy and do not modify `obj`. The `$ref` and `$src`
+ * properties are always answered by the proxy itself.
+ *
+ * The parser attaches the resolved target as `$ref` while it dereferences a document. The result is typed as
+ * `Deref<T>`, which has the shape of `T` without the raw `$ref` key, plus `$ref` and `$src`.
+ * @template T The raw OpenAPI object type being wrapped.
+ * @param obj The raw object to wrap. It is not modified.
+ * @param source Provenance information, returned by the `$src` property.
+ * @param ref The resolved target of the object's `$ref`, if it has one.
+ * @returns A proxy that behaves like `obj` and follows its reference.
+ * @see Deref
+ * @see DerefSource
+ */
 export function createDerefProxy(obj, source, ref) {
     return new Proxy(obj, new DerefProxyHandler(source, ref));
 }

package/dist/src/parse/openapi-types.d.ts

@@ -1,12 +1,25 @@
+/**
+ * Reference Object (OpenAPI 2.0 and 3.x). Points to another definition, either within the same document or in an
+ * external file or URL.
+ */
 export type OpenApiReference = {
     /**
      * Allows for an external definition of this object.
      */
     $ref: string;
 };
+/**
+ * Base shape shared by the OpenAPI object types in this file. Adds specification extensions (`x-*` keys), an optional
+ * `$ref`, and an optional type-only `__marker` that tags the kind of object.
+ * @template TMarker The string literal that identifies the object kind, such as `'info'` or `'schema'`.
+ */
 export type OpenApiObject<TMarker extends string> = Record<`x-${string}`, unknown> & Partial<OpenApiReference> & {
     __marker?: TMarker;
 };
+/**
+ * Root object of an OpenAPI document. Accepts OpenAPI 2.0 (Swagger) as well as 3.0 and 3.1 documents. Fields marked
+ * as OpenAPI 2.0 belong to Swagger documents, and the remaining fields apply to 3.x.
+ */
 export type OpenApiDocument = OpenApiObject<'document'> & {
     /**
      * The OpenAPI (v3.x) version.
@@ -89,6 +102,10 @@ export type OpenApiDocument = OpenApiObject<'document'> & {
      */
     securityDefinitions?: Record<string, OpenApiSecurityScheme>;
 };
+/**
+ * Info Object (OpenAPI 2.0 and 3.x). Provides metadata about the API, such as its title, version and license.
+ * The `summary` field exists only in OpenAPI 3.1.
+ */
 export type OpenApiInfo = OpenApiObject<'info'> & {
     /**
      * The title of the API.
@@ -119,6 +136,9 @@ export type OpenApiInfo = OpenApiObject<'info'> & {
      */
     license?: OpenApiLicense;
 };
+/**
+ * Contact Object (OpenAPI 2.0 and 3.x). Holds the contact information for the exposed API.
+ */
 export type OpenApiContact = OpenApiObject<'contact'> & {
     /**
      * The identifying name of the contact person/organization.
@@ -133,6 +153,10 @@ export type OpenApiContact = OpenApiObject<'contact'> & {
      */
     email?: string;
 };
+/**
+ * License Object (OpenAPI 2.0 and 3.x). Holds the license information for the exposed API.
+ * The `identifier` field, an SPDX license expression, exists only in OpenAPI 3.1.
+ */
 export type OpenApiLicense = OpenApiObject<'license'> & {
     /**
      * The license name used for the API.
@@ -147,6 +171,10 @@ export type OpenApiLicense = OpenApiObject<'license'> & {
      */
     identifier?: string;
 };
+/**
+ * Server Object (OpenAPI 3.x). Provides connectivity information for a target server. OpenAPI 2.0 uses `host`,
+ * `basePath` and `schemes` on the document instead.
+ */
 export type OpenApiServer = OpenApiObject<'server'> & {
     /**
      * A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
@@ -161,6 +189,9 @@ export type OpenApiServer = OpenApiObject<'server'> & {
      */
     variables?: Record<string, OpenApiServerVariable>;
 };
+/**
+ * Server Variable Object (OpenAPI 3.x). Defines a substitution value for a variable in a Server Object's URL template.
+ */
 export type OpenApiServerVariable = OpenApiObject<'server-variable'> & {
     /**
      * An enumeration of string values to be used if the substitution options are from a limited set.
@@ -175,6 +206,10 @@ export type OpenApiServerVariable = OpenApiObject<'server-variable'> & {
      */
     description?: string;
 };
+/**
+ * Fields shared by the OpenAPI 3.x Parameter and Header Objects. A Parameter Object adds `name` and `in`.
+ * @template TMarker The object kind, either `'parameter'` or `'header'`.
+ */
 export type OpenApiParameterBase<TMarker extends string> = OpenApiObject<'param-base'> & {
     /**
      * A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
@@ -223,7 +258,14 @@ export type OpenApiParameterBase<TMarker extends string> = OpenApiObject<'param-
 } & {
     __pbMarker: TMarker;
 };
+/**
+ * Header Object (OpenAPI 3.x). Describes a header of a response, or a header in an encoding.
+ * @see OpenApiParameterBase
+ */
 export type OpenApiHeader = OpenApiParameterBase<'header'>;
+/**
+ * Example Object (OpenAPI 3.x). Holds an example value, either inline or as an external URL.
+ */
 export type OpenApiExample = OpenApiObject<'example'> & {
     /**
      * Short description for the example.
@@ -242,6 +284,10 @@ export type OpenApiExample = OpenApiObject<'example'> & {
      */
     externalValue?: string;
 };
+/**
+ * Media Type Object (OpenAPI 3.x). Describes the schema, examples and encoding for one media type of a request or
+ * response body. OpenAPI 2.0 declares body schemas directly on parameters and responses instead.
+ */
 export type OpenApiMediaType = OpenApiObject<'media-type'> & {
     /**
      * The schema defining the type used for the component.
@@ -260,6 +306,9 @@ export type OpenApiMediaType = OpenApiObject<'media-type'> & {
      */
     encoding?: Record<string, OpenApiEncoding>;
 };
+/**
+ * Encoding Object (OpenAPI 3.x). Describes how a property of a multipart or form-urlencoded request body is encoded.
+ */
 export type OpenApiEncoding = OpenApiObject<'encoding'> & {
     /**
      * The Content-Type for encoding a specific property. Default value depends on the property type: for string with format being binary – application/octet-stream; for other primitive types – text/plain; for object - application/json; for array – the default is defined based on the inner type. The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the two types.
@@ -282,7 +331,15 @@ export type OpenApiEncoding = OpenApiObject<'encoding'> & {
      */
     allowReserved?: boolean;
 };
+/**
+ * HTTP methods that can be used as operation keys on a Path Item Object. OpenAPI 2.0 supports the same methods,
+ * except `trace`.
+ */
 export type OpenApiHttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+/**
+ * Path Item Object (OpenAPI 2.0 and 3.x). Groups the operations and shared parameters for one path. The `summary`,
+ * `description` and `servers` fields exist only in OpenAPI 3.x.
+ */
 export type OpenApiPathItem = OpenApiObject<'path-item'> & {
     /**
      * An optional, string summary, intended to apply to all operations in this path.
@@ -303,8 +360,20 @@ export type OpenApiPathItem = OpenApiObject<'path-item'> & {
 } & {
     [method in OpenApiHttpMethod]?: OpenApiOperation;
 };
+/**
+ * Parameter locations known to the parser. OpenAPI 3.x defines `path`, `query`, `header` and `cookie`, and OpenAPI 2.0
+ * uses `body`.
+ */
 export type KnownOpenApiParameterTarget = 'path' | 'query' | 'header' | 'cookie' | 'body' | 'form';
+/**
+ * Parameter location. Accepts a known location or any other string.
+ * @see KnownOpenApiParameterTarget
+ */
 export type OpenApiParameterTarget = KnownOpenApiParameterTarget | string;
+/**
+ * Parameter Object (OpenAPI 2.0 and 3.x). Describes one parameter of an operation or path item. The `in` field gives
+ * the location of the parameter.
+ */
 export type OpenApiParameter = OpenApiParameterBase<'parameter'> & {
     /**
      * The name of the parameter. Parameter names are case sensitive.
@@ -315,6 +384,11 @@ export type OpenApiParameter = OpenApiParameterBase<'parameter'> & {
      */
     in?: OpenApiParameterTarget;
 };
+/**
+ * Operation Object (OpenAPI 2.0 and 3.x). Describes one API operation on a path, such as a GET on `/pets`.
+ * `consumes`, `produces` and `schemes` apply only to OpenAPI 2.0, while `requestBody`, `callbacks` and `servers`
+ * apply only to OpenAPI 3.x.
+ */
 export type OpenApiOperation = OpenApiObject<'operation'> & {
     /**
      * A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
@@ -377,8 +451,15 @@ export type OpenApiOperation = OpenApiObject<'operation'> & {
      * (OpenAPI v2) The MIME types the operation can produce. This overrides the produces definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under Mime Types.
      */
     produces?: Record<string, string[]>;
+    /**
+     * (OpenAPI v2) The transfer protocols used by this operation, such as `http`, `https`, `ws` or `wss`.
+     */
     schemes?: string[];
 };
+/**
+ * External Documentation Object (OpenAPI 2.0 and 3.x). Points to additional documentation that is kept outside
+ * the API description.
+ */
 export type OpenApiExternalDocumentation = OpenApiObject<'external-doc'> & {
     /**
      * A short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
@@ -389,6 +470,10 @@ export type OpenApiExternalDocumentation = OpenApiObject<'external-doc'> & {
      */
     url: string;
 };
+/**
+ * Request Body Object (OpenAPI 3.x). Describes the body of an operation's request, keyed by media type.
+ * OpenAPI 2.0 uses a `body` parameter for this purpose.
+ */
 export type OpenApiRequestBody = OpenApiObject<'request-body'> & {
     /**
      * A brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
@@ -403,6 +488,11 @@ export type OpenApiRequestBody = OpenApiObject<'request-body'> & {
      */
     required?: boolean;
 };
+/**
+ * Response Object (OpenAPI 2.0 and 3.x). Describes one response of an operation, keyed by HTTP status code or
+ * `default`. The `schema` and `examples` fields apply only to OpenAPI 2.0, while `content` and `links` apply only to
+ * OpenAPI 3.x.
+ */
 export type OpenApiResponse = OpenApiObject<'response'> & {
     /**
      * A short description of the response. CommonMark syntax MAY be used for rich text representation.
@@ -429,6 +519,9 @@ export type OpenApiResponse = OpenApiObject<'response'> & {
      */
     examples?: Record<string, unknown>;
 };
+/**
+ * Link Object (OpenAPI 3.x). Describes how a value from a response can be used to call another operation.
+ */
 export type OpenApiLink = OpenApiObject<'link'> & {
     /**
      * A relative or absolute reference to an OAS operation. This field is mutually exclusive of the operationId field, and MUST point to an Operation Object. Relative operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition.
@@ -455,6 +548,10 @@ export type OpenApiLink = OpenApiObject<'link'> & {
      */
     server?: OpenApiServer;
 };
+/**
+ * Components Object (OpenAPI 3.x). Holds reusable objects that other parts of the document can reference with `$ref`.
+ * OpenAPI 2.0 places the equivalent definitions at the root of the document instead.
+ */
 export type OpenApiComponents = OpenApiObject<'components'> & {
     /**
      * An object to hold reusable OpenAPI objects.
@@ -497,7 +594,16 @@ export type OpenApiComponents = OpenApiObject<'components'> & {
      */
     pathItems?: Record<string, OpenApiPathItem>;
 };
+/**
+ * Security Scheme Object (OpenAPI 2.0 and 3.x). A union of the known scheme kinds, told apart by their `type` field.
+ * The known kinds are `basic` (OpenAPI 2.0 only), `http` and `openIdConnect` (OpenAPI 3.x only), and `apiKey` and
+ * `oauth2` (both versions). Any other object is also accepted.
+ */
 export type OpenApiSecurityScheme = OpenApiHttpSecurityScheme | OpenApiApiKeySecurityScheme | OpenApiOAuth2SecurityScheme | OpenApiOpenIdSecurityScheme | OpenApiObject<'security-scheme'>;
+/**
+ * Basic authentication security scheme (OpenAPI 2.0). OpenAPI 3.x expresses basic authentication as an `http`
+ * scheme with `scheme: 'basic'`.
+ */
 export type OpenApiBasicSecurityScheme = OpenApiObject<'security-scheme'> & {
     /**
      * The type of the security scheme.
@@ -508,6 +614,10 @@ export type OpenApiBasicSecurityScheme = OpenApiObject<'security-scheme'> & {
      */
     description?: string;
 };
+/**
+ * HTTP authentication security scheme (OpenAPI 3.x), such as `bearer` or `basic`. The credentials are sent in the
+ * `Authorization` header.
+ */
 export type OpenApiHttpSecurityScheme = OpenApiObject<'security-scheme'> & {
     /**
      * The type of the security scheme.
@@ -526,8 +636,20 @@ export type OpenApiHttpSecurityScheme = OpenApiObject<'security-scheme'> & {
      */
     bearerFormat?: string;
 };
+/**
+ * Locations where an API key can be sent. OpenAPI 2.0 supports `query` and `header`, and OpenAPI 3.x also supports
+ * `cookie`.
+ */
 export type KnownOpenApiApiKeySource = 'query' | 'header' | 'cookie';
+/**
+ * Location of an API key. Accepts a known location or any other string.
+ * @see KnownOpenApiApiKeySource
+ */
 export type OpenApiApiKeySource = KnownOpenApiApiKeySource | string;
+/**
+ * API key security scheme (OpenAPI 2.0 and 3.x). The key is sent in the query string, a header or a cookie, as
+ * named by `name`.
+ */
 export type OpenApiApiKeySecurityScheme = OpenApiObject<'security-scheme'> & {
     /**
      * The type of the security scheme.
@@ -546,8 +668,20 @@ export type OpenApiApiKeySecurityScheme = OpenApiObject<'security-scheme'> & {
      */
     in?: OpenApiApiKeySource;
 };
+/**
+ * OAuth 2.0 flow names known to the parser. OpenAPI 2.0 uses `implicit`, `password`, `application` and `accessCode`,
+ * and OpenAPI 3.x uses `implicit`, `password`, `clientCredentials` and `authorizationCode`.
+ */
 export type KnownOpenApiOAuth2SecurityFlow = 'implicit' | 'password' | 'application' | 'accessCode';
+/**
+ * OAuth 2.0 flow name. Accepts a known flow name or any other string.
+ * @see KnownOpenApiOAuth2SecurityFlow
+ */
 export type OpenApiOAuth2SecurityFlow = KnownOpenApiOAuth2SecurityFlow | string;
+/**
+ * OAuth 2.0 security scheme (OpenAPI 2.0 and 3.x). OpenAPI 3.x describes its flows in the `flows` object, while
+ * OpenAPI 2.0 uses the top-level `flow`, `scopes`, `authorizationUrl` and `tokenUrl` fields.
+ */
 export type OpenApiOAuth2SecurityScheme = OpenApiObject<'security-scheme'> & {
     /**
      * The type of the security scheme.
@@ -651,6 +785,9 @@ export type OpenApiOAuth2SecurityScheme = OpenApiObject<'security-scheme'> & {
      */
     tokenUrl?: string;
 };
+/**
+ * OpenID Connect security scheme (OpenAPI 3.x). The OAuth 2.0 configuration is discovered from `openIdConnectUrl`.
+ */
 export type OpenApiOpenIdSecurityScheme = OpenApiObject<'security-scheme'> & {
     /**
      * The type of the security scheme.
@@ -665,6 +802,9 @@ export type OpenApiOpenIdSecurityScheme = OpenApiObject<'security-scheme'> & {
      */
     openIdConnectUrl: string;
 };
+/**
+ * Tag Object (OpenAPI 2.0 and 3.x). Adds a name and optional metadata to a tag that is used to group operations.
+ */
 export type OpenApiTag = OpenApiObject<'tag'> & {
     /**
      * The name of the tag.
@@ -679,10 +819,30 @@ export type OpenApiTag = OpenApiObject<'tag'> & {
      */
     externalDocs?: OpenApiExternalDocumentation;
 };
+/**
+ * JSON Schema primitive type names known to the parser. `null` is a type in OpenAPI 3.1, while OpenAPI 3.0 expresses
+ * nullability with `nullable` instead.
+ */
 export type KnownOpenApiSchemaType = 'object' | 'array' | 'string' | 'number' | 'boolean' | 'integer' | 'null';
+/**
+ * JSON Schema type name. Accepts a known primitive type or any other string.
+ * @see KnownOpenApiSchemaType
+ */
 export type OpenApiSchemaType = KnownOpenApiSchemaType | string;
+/**
+ * Format names known to the parser. These include the OpenAPI formats, such as `int64`, `byte` and `password`, and
+ * the JSON Schema formats, such as `date-time` and `uri`. A format refines a `string`, `number` or `integer` schema.
+ */
 export type KnownOpenApiSchemaFormat = 'int32' | 'int64' | 'float' | 'double' | 'byte' | 'binary' | 'date' | 'date-time' | 'time' | 'duration' | 'email' | 'idn-email' | 'hostname' | 'idn-hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uri-reference' | 'iri' | 'iri-reference' | 'uri-template' | 'json-pointer' | 'relative-json-pointer' | 'regex' | 'password';
+/**
+ * Schema format name. Accepts a known format or any other string.
+ * @see KnownOpenApiSchemaFormat
+ */
 export type OpenApiSchemaFormat = KnownOpenApiSchemaFormat | string;
+/**
+ * Schema Object (OpenAPI 2.0 and 3.x). Describes the data type of a value using JSON Schema keywords. OpenAPI 2.0 uses
+ * it for parameters, responses and `definitions`, and OpenAPI 3.x uses it for components, media types and parameters.
+ */
 export type OpenApiSchema = OpenApiObject<'schema'> & {
     /**
      * Type of the schema (e.g., object, array, string, number, boolean, integer).
@@ -858,6 +1018,10 @@ export type OpenApiSchema = OpenApiObject<'schema'> & {
      */
     deprecated?: boolean;
 };
+/**
+ * Discriminator Object (OpenAPI 3.x). Names the property that selects between polymorphic schemas, and can map its
+ * values to schema names. OpenAPI 2.0 uses a plain string property name instead.
+ */
 export type OpenApiDiscriminator = OpenApiObject<'discriminator'> & {
     /**
      * The name of the property in the payload that will hold the discriminator value.
@@ -873,6 +1037,10 @@ export type OpenApiDiscriminator = OpenApiObject<'discriminator'> & {
         [key: string]: string;
     };
 };
+/**
+ * XML Object (OpenAPI 2.0 and 3.x). Controls how a schema is serialized as XML, such as its element name, its
+ * namespace, and whether it is an attribute.
+ */
 export type OpenApiXml = OpenApiObject<'xml'> & {
     /**
      * Replaces the name of the element/attribute used for the described schema property.