@samchon/openapi
Advanced tools
@samchon/openapi - npm Package Compare versions
Comparing version 0.3.0-dev.20240703 to 0.3.0
@@ -160,13 +160,43 @@ import { OpenApi } from "./OpenApi"; | ||
| export declare namespace IMigrateRoute { | ||
| /** | ||
| * Metadata of path parameter. | ||
| */ | ||
| interface IParameter<Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema> { | ||
| /** | ||
| * Name of the path parameter. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Key of the path parameter. | ||
| */ | ||
| key: string; | ||
| /** | ||
| * Metadata of path parameter data type. | ||
| */ | ||
| schema: Schema; | ||
| /** | ||
| * Description comment for the path parameter. | ||
| */ | ||
| description?: string; | ||
| } | ||
| /** | ||
| * Metadata of headers. | ||
| */ | ||
| interface IHeaders<Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema> { | ||
| /** | ||
| * Name of the headers parameter. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Key of the headers parameter. | ||
| */ | ||
| key: string; | ||
| /** | ||
| * Metadata of headers data type. | ||
| */ | ||
| schema: Schema; | ||
| } | ||
| /** | ||
| * Metadata of query values. | ||
| */ | ||
| interface IQuery<Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema> { | ||
@@ -177,13 +207,40 @@ name: string; | ||
| } | ||
| /** | ||
| * Metadata of request/response body. | ||
| */ | ||
| interface IBody<Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema> { | ||
| /** | ||
| * Name of the body parameter. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Key of the body parameter. | ||
| */ | ||
| key: string; | ||
| /** | ||
| * Content type of the body. | ||
| */ | ||
| type: "text/plain" | "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data"; | ||
| /** | ||
| * Metadata of response body data type. | ||
| */ | ||
| schema: Schema; | ||
| /** | ||
| * Whether the body is encrypted or not. | ||
| */ | ||
| "x-nestia-encrypted"?: boolean; | ||
| } | ||
| /** | ||
| * Metadata of response body for exceptional status cases. | ||
| */ | ||
| interface IException<Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema> { | ||
| /** | ||
| * Description comment for the exception. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * Metadata of response body data type. | ||
| */ | ||
| schema: Schema; | ||
| } | ||
| } |
@@ -26,3 +26,3 @@ import { IMigrateDocument } from "./IMigrateDocument"; | ||
| * - Merged {@link OpenApiV3_1.IPath.parameters} to {@link OpenApi.IOperation.parameters} | ||
| * - Resolved {@link OpenApi.IJsonSchema.IReference references} of {@link OpenApiV3_1.IOperation} mebers | ||
| * - Resolved {@link OpenApi.IJsonSchema.IReference references} of {@link OpenApiV3_1.IOperation} members | ||
| * - JSON Schema | ||
@@ -40,2 +40,5 @@ * - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed} | ||
| export declare namespace OpenApi { | ||
| /** | ||
| * Method of the operation. | ||
| */ | ||
| type Method = "get" | "post" | "put" | "delete" | "options" | "head" | "patch" | "trace"; | ||
@@ -69,69 +72,299 @@ /** | ||
| function downgrade<Schema extends IJsonSchema = IJsonSchema, Operation extends IOperation<Schema> = IOperation<Schema>>(document: IDocument<Schema, Operation>, version: "3.0"): OpenApiV3.IDocument; | ||
| /** | ||
| * Convert to migrate document. | ||
| * | ||
| * Convert the given OpenAPI document to {@link IMigrateDocument}, that is | ||
| * useful for OpenAPI generator library which makes RPC (Remote Procedure Call) | ||
| * functions for the Restful API operation. | ||
| * | ||
| * @param document OpenAPI document to migrate | ||
| * @returns Migrated document | ||
| */ | ||
| function migrate<Schema extends IJsonSchema = IJsonSchema, Operation extends IOperation<Schema> = IOperation<Schema>>(document: IDocument<Schema, Operation>): IMigrateDocument<Schema, Operation>; | ||
| /** | ||
| * OpenAPI document. | ||
| * | ||
| * `OpenApi.IDocument` represents an OpenAPI document of emended OpenAPI v3.1. | ||
| * | ||
| * In other words, `OpenApi.IDocument` is a structure of `swagger.json` file of | ||
| * OpenAPI v3.1 specification, but a little bit shrinked to remove ambiguous and | ||
| * duplicated expressions of OpenAPI v3.1 for the convenience and clarity. | ||
| * | ||
| * @template Schema JSON schema type | ||
| * @template Operation HTTP operation type | ||
| */ | ||
| interface IDocument<Schema extends IJsonSchema = IJsonSchema, Operation extends IOperation<Schema> = IOperation<Schema>> { | ||
| /** | ||
| * OpenAPI version number. | ||
| */ | ||
| openapi: `3.1.${number}`; | ||
| /** | ||
| * List of servers that provide the API. | ||
| */ | ||
| servers?: IServer[]; | ||
| /** | ||
| * Information about the API. | ||
| */ | ||
| info?: IDocument.IInfo; | ||
| /** | ||
| * An object to hold reusable data structures. | ||
| * | ||
| * It stores both DTO schemas and security schemes. | ||
| * | ||
| * For reference, `nestia` defines every object and alias types as reusable DTO | ||
| * schemas. The alias type means that defined by `type` keyword in TypeScript. | ||
| */ | ||
| components: IComponents<Schema>; | ||
| /** | ||
| * The available paths and operations for the API. | ||
| * | ||
| * The 1st key is the path, and the 2nd key is the HTTP method. | ||
| */ | ||
| paths?: Record<string, IPath<Schema, Operation>>; | ||
| /** | ||
| * An object to hold Webhooks. | ||
| * | ||
| * Its structure is same with {@link paths}, so that the 1st key is the path, | ||
| * and the 2nd key is the HTTP method. | ||
| */ | ||
| webhooks?: Record<string, IPath<Schema, Operation>>; | ||
| /** | ||
| * A declaration of which security mechanisms can be used across the API. | ||
| * | ||
| * When this property be configured, it would be overwritten in every API routes. | ||
| * | ||
| * For reference, key means the name of security scheme and value means the `scopes`. | ||
| * The `scopes` can be used only when target security scheme is `oauth2` type, | ||
| * especially for {@link ISwaggerSecurityScheme.IOAuth2.IFlow.scopes} property. | ||
| */ | ||
| security?: Record<string, string[]>[]; | ||
| /** | ||
| * List of tag names with description. | ||
| * | ||
| * It is possible to omit this property or skip some tag name even if | ||
| * the tag name is used in the API routes. In that case, the tag name | ||
| * would be displayed (in Swagger-UI) without description. | ||
| */ | ||
| tags?: IDocument.ITag[]; | ||
| /** | ||
| * Flag for indicating this document is emended by `@samchon/openapi`. | ||
| */ | ||
| "x-samchon-emended": true; | ||
| } | ||
| namespace IDocument { | ||
| /** | ||
| * Information about the API. | ||
| */ | ||
| interface IInfo { | ||
| /** | ||
| * The title of the API. | ||
| */ | ||
| title: string; | ||
| /** | ||
| * A short summary of the API. | ||
| */ | ||
| summary?: string; | ||
| /** | ||
| * A full description of the API. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * A URL to the Terms of Service for the API. | ||
| */ | ||
| termsOfService?: string; | ||
| /** | ||
| * The contact information for the exposed API. | ||
| */ | ||
| contact?: IContact; | ||
| /** | ||
| * The license information for the exposed API. | ||
| */ | ||
| license?: ILicense; | ||
| /** | ||
| * Version of the API. | ||
| */ | ||
| version: string; | ||
| } | ||
| /** | ||
| * OpenAPI tag information. | ||
| * | ||
| * It is possible to skip composing this structure, even if some | ||
| * tag names are regsitered in the API routes ({@link OpenApi.IOperation.tags}). | ||
| * In that case, the tag name would be displayed in Swagger-UI without | ||
| * description. | ||
| * | ||
| * However, if you want to describe the tag name, you can compose this | ||
| * structure and describe the tag name in the {@link description} property. | ||
| */ | ||
| interface ITag { | ||
| /** | ||
| * The name of the tag. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * An optional string describing the tag. | ||
| */ | ||
| description?: string; | ||
| } | ||
| /** | ||
| * Contact information for the exposed API. | ||
| */ | ||
| interface IContact { | ||
| /** | ||
| * The identifying name of the contact person/organization. | ||
| */ | ||
| name?: string; | ||
| /** | ||
| * The URL pointing to the contact information. | ||
| */ | ||
| url?: string; | ||
| /** | ||
| * The email address of the contact person/organization. | ||
| * | ||
| * @format email | ||
| */ | ||
| email?: string; | ||
| } | ||
| /** | ||
| * License information for the exposed API. | ||
| */ | ||
| interface ILicense { | ||
| /** | ||
| * The license name used for the API. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Identifier for the license used for the API. | ||
| * | ||
| * example: MIT | ||
| */ | ||
| identifier?: string; | ||
| /** | ||
| * A URL to the license used for the API. | ||
| */ | ||
| url?: string; | ||
| } | ||
| } | ||
| /** | ||
| * The remote server that provides the API. | ||
| */ | ||
| interface IServer { | ||
| /** | ||
| * A URL to the target host. | ||
| */ | ||
| url: string; | ||
| /** | ||
| * An optional string describing the target server. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * A map between a variable name and its value. | ||
| * | ||
| * When the server {@link url} is a type of template, this property | ||
| * would be utilized to fill the template with actual values. | ||
| */ | ||
| variables?: Record<string, IServer.IVariable>; | ||
| } | ||
| namespace IServer { | ||
| /** | ||
| * A variable for the server URL template. | ||
| */ | ||
| interface IVariable { | ||
| /** | ||
| * Default value to use for substitution. | ||
| */ | ||
| default: string; | ||
| /** @minItems 1 */ enum?: string[]; | ||
| /** | ||
| * List of available values for the variable. | ||
| */ | ||
| enum?: string[]; | ||
| /** | ||
| * An optional description for the server variable. | ||
| */ | ||
| description?: string; | ||
| } | ||
| } | ||
| type IPath<Schema extends IJsonSchema = IJsonSchema, Operation extends IOperation<Schema> = IOperation<Schema>> = { | ||
| /** | ||
| * Path item. | ||
| * | ||
| * `OpenApi.IPath` represents a path item of emended OpenAPI v3.1, | ||
| * collecting multiple method operations in a signgle path. | ||
| */ | ||
| interface IPath<Schema extends IJsonSchema = IJsonSchema, Operation extends IOperation<Schema> = IOperation<Schema>> extends Partial<Record<Method, Operation>> { | ||
| /** | ||
| * Servers that provide the path operations. | ||
| */ | ||
| servers?: IServer[]; | ||
| /** | ||
| * Summary of the path. | ||
| */ | ||
| summary?: string; | ||
| /** | ||
| * Description of the path. | ||
| */ | ||
| description?: string; | ||
| } & Partial<Record<Method, Operation>>; | ||
| } | ||
| /** | ||
| * Remote operation info. | ||
| * | ||
| * `OpenApi.IOperation` represents an Restful API operation provided by the | ||
| * remote server. | ||
| */ | ||
| interface IOperation<Schema extends IJsonSchema = IJsonSchema> { | ||
| /** | ||
| * Unique string used to identify the operation. | ||
| */ | ||
| operationId?: string; | ||
| /** | ||
| * List of parameters that are applicable for this operation. | ||
| */ | ||
| parameters?: IOperation.IParameter<Schema>[]; | ||
| /** | ||
| * The request body applicable for this operation. | ||
| */ | ||
| requestBody?: IOperation.IRequestBody<Schema>; | ||
| /** | ||
| * The list of possible responses as they are returned from executing this | ||
| * operation. Its key is the HTTP status code, and the value is the metadata of | ||
| * the response in the HTTP status code. | ||
| */ | ||
| responses?: Record<string, IOperation.IResponse<Schema>>; | ||
| /** | ||
| * A list of servers providing this API operation. | ||
| */ | ||
| servers?: IServer[]; | ||
| /** | ||
| * A short summary of what the operation does. | ||
| */ | ||
| summary?: string; | ||
| /** | ||
| * A verbose explanation of the operation behavior. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * List of securities and their scopes that are required for execution. | ||
| * | ||
| * When this property be configured, the Restful API operation requires | ||
| * the matched security value for exection. Its key means security key | ||
| * matched with {@link OpenApi.IDocument.security}. | ||
| * | ||
| * The value means scopes required for the security key when the security | ||
| * type is {@link OpenApi.ISecurityScheme.IOAuth2}. Otherwise the target | ||
| * security type is not {@link OpenApi.ISecurityScheme.IOAuth2}, the value | ||
| * would be empty array. | ||
| */ | ||
| security?: Record<string, string[]>[]; | ||
| /** | ||
| * Tags for API documentation control. | ||
| */ | ||
| tags?: string[]; | ||
| /** | ||
| * Flag for indicating this operation is deprecated. | ||
| */ | ||
| deprecated?: boolean; | ||
| } | ||
| namespace IOperation { | ||
| /** | ||
| * Parameter of the operation. | ||
| */ | ||
| interface IParameter<Schema extends IJsonSchema = IJsonSchema> { | ||
@@ -145,2 +378,5 @@ name?: string; | ||
| } | ||
| /** | ||
| * Request body of the operation. | ||
| */ | ||
| interface IRequestBody<Schema extends IJsonSchema = IJsonSchema> { | ||
@@ -152,2 +388,5 @@ description?: string; | ||
| } | ||
| /** | ||
| * Response of the operation. | ||
| */ | ||
| interface IResponse<Schema extends IJsonSchema = IJsonSchema> { | ||
@@ -159,27 +398,118 @@ content?: IContent<Schema>; | ||
| } | ||
| /** | ||
| * List of content types supported in request/response body. | ||
| */ | ||
| type IContent<Schema extends IJsonSchema = IJsonSchema> = Partial<Record<ContentType, IMediaType<Schema>>>; | ||
| /** | ||
| * Media type of a request/response body. | ||
| */ | ||
| interface IMediaType<Schema extends IJsonSchema = IJsonSchema> { | ||
| schema?: Schema; | ||
| } | ||
| /** | ||
| * List of supported content media types. | ||
| */ | ||
| type ContentType = "text/plain" | "application/json" | "application/x-www-form-url-encoded" | "multipart/form-data" | "*/*" | (string & {}); | ||
| } | ||
| /** | ||
| * Reusable components in OpenAPI. | ||
| * | ||
| * A storage of reusable components in OpenAPI document. | ||
| * | ||
| * In other words, it is a storage of named DTO schemas and security schemes. | ||
| */ | ||
| interface IComponents<Schema extends IJsonSchema = IJsonSchema> { | ||
| /** | ||
| * An object to hold reusable DTO schemas. | ||
| * | ||
| * In other words, a collection of named JSON schemas. | ||
| */ | ||
| schemas?: Record<string, Schema>; | ||
| /** | ||
| * An object to hold reusable security schemes. | ||
| * | ||
| * In other words, a collection of named security schemes. | ||
| */ | ||
| securitySchemes?: Record<string, ISecurityScheme>; | ||
| } | ||
| /** | ||
| * Type schema info. | ||
| * | ||
| * `OpenApi.IJsonSchema` is a type schema info of the OpenAPI. | ||
| * | ||
| * `OpenApi.IJsonSchema` basically follows the JSON schema definition of | ||
| * OpenAPI v3.1, but a little bit shrinked to remove ambiguous and duplicated | ||
| * expressions of OpenAPI v3.1 for the convenience and clarity. | ||
| * | ||
| * - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed} | ||
| * - Resolve nullable property: {@link OpenApiV3_1.IJsonSchema.__ISignificant.nullable} | ||
| * - Array type utilizes only single {@link OpenAPI.IJsonSchema.IArray.items} | ||
| * - Tuple type utilizes only {@link OpenApi.IJsonSchema.ITuple.prefixItems} | ||
| * - Merge {@link OpenApiV3_1.IJsonSchema.IAnyOf} to {@link OpenApi.IJsonSchema.IOneOf} | ||
| * - Merge {@link OpenApiV3_1.IJsonSchema.IRecursiveReference} to {@link OpenApi.IJsonSchema.IReference} | ||
| * - Merge {@link OpenApiV3_1.IJsonSchema.IAllOf} to {@link OpenApi.IJsonSchema.IObject} | ||
| */ | ||
| type IJsonSchema = IJsonSchema.IConstant | IJsonSchema.IBoolean | IJsonSchema.IInteger | IJsonSchema.INumber | IJsonSchema.IString | IJsonSchema.IArray | IJsonSchema.ITuple | IJsonSchema.IObject | IJsonSchema.IReference | IJsonSchema.IOneOf | IJsonSchema.INull | IJsonSchema.IUnknown; | ||
| namespace IJsonSchema { | ||
| /** | ||
| * Constant value type. | ||
| */ | ||
| interface IConstant extends __IAttribute { | ||
| /** | ||
| * The constant value. | ||
| */ | ||
| const: boolean | number | string; | ||
| } | ||
| /** | ||
| * Boolean type info. | ||
| */ | ||
| interface IBoolean extends __ISignificant<"boolean"> { | ||
| /** | ||
| * The default value. | ||
| */ | ||
| default?: boolean; | ||
| } | ||
| /** | ||
| * Integer type info. | ||
| */ | ||
| interface IInteger extends __ISignificant<"integer"> { | ||
| /** @type int64 */ default?: number; | ||
| /** @type int64 */ minimum?: number; | ||
| /** @type int64 */ maximum?: number; | ||
| /** | ||
| * Default value. | ||
| * | ||
| * @type int64 | ||
| */ | ||
| default?: number; | ||
| /** | ||
| * Minimum value restriction. | ||
| * | ||
| * @type int64 | ||
| */ | ||
| minimum?: number; | ||
| /** | ||
| * Maximum value restriction. | ||
| * | ||
| * @type int64 | ||
| */ | ||
| maximum?: number; | ||
| /** | ||
| * Exclusive minimum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMinimum` value as `number`, {@link OpenApi} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link minimum} property. | ||
| */ | ||
| exclusiveMinimum?: boolean; | ||
| /** | ||
| * Exclusive maximum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMaximum` value as `number`, {@link OpenApi} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link maximum} property. | ||
| */ | ||
| exclusiveMaximum?: boolean; | ||
| /** | ||
| * Multiple of value restriction. | ||
| * | ||
| * @type uint64 | ||
@@ -190,58 +520,315 @@ * @exclusiveMinimum 0 | ||
| } | ||
| /** | ||
| * Number (double) type info. | ||
| */ | ||
| interface INumber extends __ISignificant<"number"> { | ||
| /** | ||
| * Default value. | ||
| */ | ||
| default?: number; | ||
| /** | ||
| * Minimum value restriction. | ||
| */ | ||
| minimum?: number; | ||
| /** | ||
| * Maximum value restriction. | ||
| */ | ||
| maximum?: number; | ||
| /** | ||
| * Exclusive minimum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMinimum` value as `number`, {@link OpenAiComposer} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link minimum} property. | ||
| */ | ||
| exclusiveMinimum?: boolean; | ||
| /** | ||
| * Exclusive maximum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMaximum` value as `number`, {@link OpenAiComposer} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link maximum} property. | ||
| */ | ||
| exclusiveMaximum?: boolean; | ||
| /** @exclusiveMinimum 0 */ multipleOf?: number; | ||
| /** | ||
| * Multiple of value restriction. | ||
| * | ||
| * @exclusiveMinimum 0 | ||
| */ | ||
| multipleOf?: number; | ||
| } | ||
| /** | ||
| * String type info. | ||
| */ | ||
| interface IString extends __ISignificant<"string"> { | ||
| contentMediaType?: string; | ||
| /** | ||
| * Default value. | ||
| */ | ||
| default?: string; | ||
| /** | ||
| * Format restriction. | ||
| */ | ||
| format?: "binary" | "byte" | "password" | "regex" | "uuid" | "email" | "hostname" | "idn-email" | "idn-hostname" | "iri" | "iri-reference" | "ipv4" | "ipv6" | "uri" | "uri-reference" | "uri-template" | "url" | "date-time" | "date" | "time" | "duration" | "json-pointer" | "relative-json-pointer" | (string & {}); | ||
| /** | ||
| * Pattern restriction. | ||
| */ | ||
| pattern?: string; | ||
| /** @type uint64 */ minLength?: number; | ||
| /** @type uint64 */ maxLength?: number; | ||
| /** | ||
| * Content media type restriction. | ||
| */ | ||
| contentMediaType?: string; | ||
| /** | ||
| * Minimum length restriction. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| minLength?: number; | ||
| /** | ||
| * Maximum length restriction. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| maxLength?: number; | ||
| } | ||
| /** | ||
| * Array type. | ||
| */ | ||
| interface IArray<Schema extends IJsonSchema = IJsonSchema> extends __ISignificant<"array"> { | ||
| /** | ||
| * Items type info. | ||
| * | ||
| * The `items` means the type of the array elements. In other words, it is | ||
| * the type schema info of the `T` in the TypeScript array type `Array<T>`. | ||
| */ | ||
| items: Schema; | ||
| /** | ||
| * Unique items restriction. | ||
| * | ||
| * If this property value is `true`, target array must have unique items. | ||
| */ | ||
| uniqueItems?: boolean; | ||
| /** @type uint64 */ minItems?: number; | ||
| /** @type uint64 */ maxItems?: number; | ||
| /** | ||
| * Minimum items restriction. | ||
| * | ||
| * Restriction of minumum number of items in the array. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| minItems?: number; | ||
| /** | ||
| * Maximum items restriction. | ||
| * | ||
| * Restriction of maximum number of items in the array. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| maxItems?: number; | ||
| } | ||
| /** | ||
| * Tuple type info. | ||
| */ | ||
| interface ITuple<Schema extends IJsonSchema = IJsonSchema> extends __ISignificant<"array"> { | ||
| /** | ||
| * Prefix items. | ||
| * | ||
| * The `prefixItems` means the type schema info of the prefix items in the | ||
| * tuple type. In the TypeScript, it is expressed as `[T1, T2]`. | ||
| * | ||
| * If you want to express `[T1, T2, ...TO[]]` type, you can configure the | ||
| * `...TO[]` through the {@link additionalItems} property. | ||
| */ | ||
| prefixItems: Schema[]; | ||
| /** | ||
| * Additional items. | ||
| * | ||
| * The `additionalItems` means the type schema info of the additional items | ||
| * after the {@link prefixItems}. In the TypeScript, if there's a type | ||
| * `[T1, T2, ...TO[]]`, the `...TO[]` is represented by the `additionalItems`. | ||
| * | ||
| * By the way, if you configure the `additionalItems` as `true`, it means | ||
| * the additional items are not restricted. They can be any type, so that | ||
| * it is equivalent to the TypeScript type `[T1, T2, ...any[]]`. | ||
| * | ||
| * Otherwise configure the `additionalItems` as the {@link IJsonSchema}, | ||
| * it means the additional items must follow the type schema info. | ||
| * Therefore, it is equivalent to the TypeScript type `[T1, T2, ...TO[]]`. | ||
| */ | ||
| additionalItems?: boolean | Schema; | ||
| /** | ||
| * Unique items restriction. | ||
| * | ||
| * If this property value is `true`, target tuple must have unique items. | ||
| */ | ||
| uniqueItems?: boolean; | ||
| /** @type uint64 */ minItems?: number; | ||
| /** @type uint64 */ maxItems?: number; | ||
| /** | ||
| * Minimum items restriction. | ||
| * | ||
| * Restriction of minumum number of items in the tuple. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| minItems?: number; | ||
| /** | ||
| * Maximum items restriction. | ||
| * | ||
| * Restriction of maximum number of items in the tuple. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| maxItems?: number; | ||
| } | ||
| /** | ||
| * Object type info. | ||
| */ | ||
| interface IObject<Schema extends IJsonSchema = IJsonSchema> extends __ISignificant<"object"> { | ||
| /** | ||
| * Properties of the object. | ||
| * | ||
| * The `properties` means a list of key-value pairs of the object's | ||
| * regular properties. The key is the name of the regular property, | ||
| * and the value is the type schema info. | ||
| * | ||
| * If you need additional properties that is represented by dynamic key, | ||
| * you can use the {@link additionalProperties} instead. | ||
| */ | ||
| properties?: Record<string, Schema>; | ||
| /** | ||
| * Additional properties' info. | ||
| * | ||
| * The `additionalProperties` means the type schema info of the additional | ||
| * properties that are not listed in the {@link properties}. | ||
| * | ||
| * If the value is `true`, it means that the additional properties are not | ||
| * restricted. They can be any type. Otherwise, if the value is | ||
| * {@link IOpenAiSchema} type, it means that the additional properties must | ||
| * follow the type schema info. | ||
| * | ||
| * - `true`: `Record<string, any>` | ||
| * - `IOpenAiSchema`: `Record<string, T>` | ||
| */ | ||
| additionalProperties?: boolean | Schema; | ||
| /** | ||
| * List of key values of the required properties. | ||
| * | ||
| * The `required` means a list of the key values of the required | ||
| * {@link properties}. If some property key is not listed in the `required` | ||
| * list, it means that property is optional. Otherwise some property key | ||
| * exists in the `required` list, it means that the property must be filled. | ||
| * | ||
| * Below is an example of the {@link properties} and `required`. | ||
| * | ||
| * ```typescript | ||
| * interface SomeObject { | ||
| * id: string; | ||
| * email: string; | ||
| * name?: string; | ||
| * } | ||
| * ``` | ||
| * | ||
| * As you can see, `id` and `email` {@link properties} are {@link required}, | ||
| * so that they are listed in the `required` list. | ||
| * | ||
| * ```json | ||
| * { | ||
| * "type": "object", | ||
| * "properties": { | ||
| * "id": { "type": "string" }, | ||
| * "email": { "type": "string" }, | ||
| * "name": { "type": "string" } | ||
| * }, | ||
| * "required": ["id", "email"] | ||
| * } | ||
| * ``` | ||
| */ | ||
| required?: string[]; | ||
| } | ||
| /** | ||
| * Reference type directing named schema. | ||
| */ | ||
| interface IReference<Key = string> extends __IAttribute { | ||
| /** | ||
| * Reference to the named schema. | ||
| * | ||
| * The `ref` is a reference to the named schema. Format of the `$ref` is | ||
| * following the JSON Pointer specification. In the OpenAPI, the `$ref` | ||
| * starts with `#/components/schemas/` which means the type is stored in | ||
| * the {@link OpenApi.IComponents.schemas} object. | ||
| * | ||
| * - `#/components/schemas/SomeObject` | ||
| * - `#/components/schemas/AnotherObject` | ||
| */ | ||
| $ref: Key; | ||
| } | ||
| /** | ||
| * Union type. | ||
| * | ||
| * IOneOf` represents an union type of the TypeScript (`A | B | C`). | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined `anyOf` instead of the `oneOf`, {@link OpenApi} forcibly | ||
| * converts it to `oneOf` type. | ||
| */ | ||
| interface IOneOf<Schema extends IJsonSchema = IJsonSchema> extends __IAttribute { | ||
| oneOf: Exclude<IJsonSchema, IJsonSchema.IOneOf>[]; | ||
| /** | ||
| * List of the union types. | ||
| */ | ||
| oneOf: Exclude<Schema, IJsonSchema.IOneOf>[]; | ||
| } | ||
| /** | ||
| * Null type. | ||
| */ | ||
| interface INull extends __ISignificant<"null"> { | ||
| } | ||
| /** | ||
| * Unknown, `any` type. | ||
| */ | ||
| interface IUnknown extends __IAttribute { | ||
| /** | ||
| * Type is never be defined. | ||
| */ | ||
| type?: undefined; | ||
| } | ||
| /** | ||
| * Significant attributes that can be applied to the most types. | ||
| */ | ||
| interface __ISignificant<Type extends string> extends __IAttribute { | ||
| /** | ||
| * Discriminator value of the type. | ||
| */ | ||
| type: Type; | ||
| } | ||
| /** | ||
| * Common attributes that can be applied to all types. | ||
| */ | ||
| interface __IAttribute { | ||
| /** | ||
| * Title of the schema. | ||
| */ | ||
| title?: string; | ||
| /** | ||
| * Detailed description of the schema. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * Whether the type is deprecated or not. | ||
| */ | ||
| deprecated?: boolean; | ||
| } | ||
| } | ||
| /** | ||
| * Security scheme of Swagger Documents. | ||
| * | ||
| * `OpenApi.ISecurityScheme` is a data structure representing content of | ||
| * `securitySchemes` in `swagger.json` file. It is composed with 5 types of | ||
| * security schemes as an union type like below. | ||
| * | ||
| * @reference https://swagger.io/specification/#security-scheme-object | ||
| */ | ||
| type ISecurityScheme = ISecurityScheme.IApiKey | ISecurityScheme.IHttpBasic | ISecurityScheme.IHttpBearer | ISecurityScheme.IOAuth2 | ISecurityScheme.IOpenId; | ||
| namespace ISecurityScheme { | ||
| /** | ||
| * Normal API key type. | ||
| */ | ||
| interface IApiKey { | ||
@@ -253,2 +840,5 @@ type: "apiKey"; | ||
| } | ||
| /** | ||
| * HTTP basic authentication type. | ||
| */ | ||
| interface IHttpBasic { | ||
@@ -259,2 +849,5 @@ type: "http"; | ||
| } | ||
| /** | ||
| * HTTP bearer authentication type. | ||
| */ | ||
| interface IHttpBearer { | ||
@@ -266,2 +859,5 @@ type: "http"; | ||
| } | ||
| /** | ||
| * OAuth2 authentication type. | ||
| */ | ||
| interface IOAuth2 { | ||
@@ -268,0 +864,0 @@ type: "oauth2"; |
@@ -34,3 +34,3 @@ "use strict"; | ||
| * - Merged {@link OpenApiV3_1.IPath.parameters} to {@link OpenApi.IOperation.parameters} | ||
| * - Resolved {@link OpenApi.IJsonSchema.IReference references} of {@link OpenApiV3_1.IOperation} mebers | ||
| * - Resolved {@link OpenApi.IJsonSchema.IReference references} of {@link OpenApiV3_1.IOperation} members | ||
| * - JSON Schema | ||
@@ -65,2 +65,5 @@ * - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed} | ||
| OpenApi.convert = convert; | ||
| /** | ||
| * @internal | ||
| */ | ||
| function downgrade(document, version) { | ||
@@ -74,2 +77,12 @@ if (version === "2.0") | ||
| OpenApi.downgrade = downgrade; | ||
| /** | ||
| * Convert to migrate document. | ||
| * | ||
| * Convert the given OpenAPI document to {@link IMigrateDocument}, that is | ||
| * useful for OpenAPI generator library which makes RPC (Remote Procedure Call) | ||
| * functions for the Restful API operation. | ||
| * | ||
| * @param document OpenAPI document to migrate | ||
| * @returns Migrated document | ||
| */ | ||
| function migrate(document) { | ||
@@ -76,0 +89,0 @@ return MigrateConverter_1.MigrateConverter.convert(document); |
| { | ||
| "name": "@samchon/openapi", | ||
| "version": "0.3.0-dev.20240703", | ||
| "version": "0.3.0", | ||
| "description": "OpenAPI definitions and converters for 'typia' and 'nestia'.", | ||
@@ -11,3 +11,3 @@ "main": "./lib/index.js", | ||
| "build:main": "rimraf lib && tsc", | ||
| "build:test": "rimraf bin && tsc -p tsconfig.test.json", | ||
| "build:test": "rimraf bin && tsc -p test/tsconfig.json", | ||
| "dev": "npm run build:test -- --watch", | ||
@@ -34,2 +34,3 @@ "test": "node bin/test" | ||
| "@nestia/e2e": "^0.6.0", | ||
| "@trivago/prettier-plugin-sort-imports": "^4.3.0", | ||
| "@types/node": "^20.12.7", | ||
@@ -36,0 +37,0 @@ "prettier": "^3.2.5", |
@@ -22,19 +22,19 @@ # `@samchon/openapi` | ||
| - `{ type: ["string", "null"] }` | ||
| - `{ type: "string", nullable: true }` | ||
| - `{ oneOf: [{ type: "string" }, { type: "null" }] }` | ||
| - `{ type: ["string", "null"] }` | ||
| - `{ type: "string", nullable: true }` | ||
| - `{ oneOf: [{ type: "string" }, { type: "null" }] }` | ||
| Here is the entire list of differences between OpenAPI v3.1 and emended OpenApi. | ||
| - Operation | ||
| - Merge `OpenApiV3_1.IPathItem.parameters` to `OpenApi.IOperation.parameters` | ||
| - Resolve references of `OpenApiV3_1.IOperation` members | ||
| - JSON Schema | ||
| - Decompose mixed type: `OpenApiV3_1.IJsonSchema.IMixed` | ||
| - Resolve nullable property: `OpenApiV3_1.IJsonSchema.__ISignificant.nullable` | ||
| - Array type utilizes only single `OpenAPI.IJsonSchema.IArray.items` | ||
| - Tuple type utilizes only `OpenApi.IJsonSchema.ITuple.prefixItems` | ||
| - Merge `OpenApiV3_1.IJsonSchema.IAnyOf` to `OpenApi.IJsonSchema.IOneOf` | ||
| - Merge `OpenApiV3_1.IJsonSchema.IRecursiveReference` to `OpenApi.IJsonSchema.IReference` | ||
| - Merge `OpenApiV3_1.IJsonSchema.IAllOf` to `OpenApi.IJsonSchema.IObject` | ||
| - Operation | ||
| - Merge `OpenApiV3_1.IPathItem.parameters` to `OpenApi.IOperation.parameters` | ||
| - Resolve references of `OpenApiV3_1.IOperation` members | ||
| - JSON Schema | ||
| - Decompose mixed type: `OpenApiV3_1.IJsonSchema.IMixed` | ||
| - Resolve nullable property: `OpenApiV3_1.IJsonSchema.__ISignificant.nullable` | ||
| - Array type utilizes only single `OpenAPI.IJsonSchema.IArray.items` | ||
| - Tuple type utilizes only `OpenApi.IJsonSchema.ITuple.prefixItems` | ||
| - Merge `OpenApiV3_1.IJsonSchema.IAnyOf` to `OpenApi.IJsonSchema.IOneOf` | ||
| - Merge `OpenApiV3_1.IJsonSchema.IRecursiveReference` to `OpenApi.IJsonSchema.IReference` | ||
| - Merge `OpenApiV3_1.IJsonSchema.IAllOf` to `OpenApi.IJsonSchema.IObject` | ||
@@ -84,5 +84,6 @@ Additionally, `@samchon/openapi` provides [`IMigrateDocument`](https://github.com/samchon/openapi/blob/master/src/IMigrateDocument.ts) for OpenAPI generators. | ||
| ## Related Projects | ||
| - `typia`: https://github.com/samchon/typia | ||
| - `nestia`: https://github.com/samchon/nestia | ||
| - `@nestia/editor`: https://nestia.io/docs/editor | ||
| - `typia`: https://github.com/samchon/typia | ||
| - `nestia`: https://github.com/samchon/nestia | ||
| - `@wrtnio/openai-function-schema`: https://github.com/wrtnio/openai-function-schema |
@@ -175,17 +175,54 @@ import { OpenApi } from "./OpenApi"; | ||
| export namespace IMigrateRoute { | ||
| /** | ||
| * Metadata of path parameter. | ||
| */ | ||
| export interface IParameter< | ||
| Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema, | ||
| > { | ||
| /** | ||
| * Name of the path parameter. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Key of the path parameter. | ||
| */ | ||
| key: string; | ||
| /** | ||
| * Metadata of path parameter data type. | ||
| */ | ||
| schema: Schema; | ||
| /** | ||
| * Description comment for the path parameter. | ||
| */ | ||
| description?: string; | ||
| } | ||
| /** | ||
| * Metadata of headers. | ||
| */ | ||
| export interface IHeaders< | ||
| Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema, | ||
| > { | ||
| name: string; // headers | ||
| key: string; // headers | ||
| /** | ||
| * Name of the headers parameter. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Key of the headers parameter. | ||
| */ | ||
| key: string; | ||
| /** | ||
| * Metadata of headers data type. | ||
| */ | ||
| schema: Schema; | ||
| } | ||
| /** | ||
| * Metadata of query values. | ||
| */ | ||
| export interface IQuery< | ||
@@ -198,7 +235,22 @@ Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema, | ||
| } | ||
| /** | ||
| * Metadata of request/response body. | ||
| */ | ||
| export interface IBody< | ||
| Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema, | ||
| > { | ||
| /** | ||
| * Name of the body parameter. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Key of the body parameter. | ||
| */ | ||
| key: string; | ||
| /** | ||
| * Content type of the body. | ||
| */ | ||
| type: | ||
@@ -209,11 +261,30 @@ | "text/plain" | ||
| | "multipart/form-data"; | ||
| /** | ||
| * Metadata of response body data type. | ||
| */ | ||
| schema: Schema; | ||
| /** | ||
| * Whether the body is encrypted or not. | ||
| */ | ||
| "x-nestia-encrypted"?: boolean; | ||
| } | ||
| /** | ||
| * Metadata of response body for exceptional status cases. | ||
| */ | ||
| export interface IException< | ||
| Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema, | ||
| > { | ||
| /** | ||
| * Description comment for the exception. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * Metadata of response body data type. | ||
| */ | ||
| schema: Schema; | ||
| } | ||
| } |
@@ -33,3 +33,3 @@ import { IMigrateDocument } from "./IMigrateDocument"; | ||
| * - Merged {@link OpenApiV3_1.IPath.parameters} to {@link OpenApi.IOperation.parameters} | ||
| * - Resolved {@link OpenApi.IJsonSchema.IReference references} of {@link OpenApiV3_1.IOperation} mebers | ||
| * - Resolved {@link OpenApi.IJsonSchema.IReference references} of {@link OpenApiV3_1.IOperation} members | ||
| * - JSON Schema | ||
@@ -47,2 +47,5 @@ * - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed} | ||
| export namespace OpenApi { | ||
| /** | ||
| * Method of the operation. | ||
| */ | ||
| export type Method = | ||
@@ -120,2 +123,5 @@ | "get" | ||
| /** | ||
| * @internal | ||
| */ | ||
| export function downgrade< | ||
@@ -133,2 +139,12 @@ Schema extends IJsonSchema = IJsonSchema, | ||
| /** | ||
| * Convert to migrate document. | ||
| * | ||
| * Convert the given OpenAPI document to {@link IMigrateDocument}, that is | ||
| * useful for OpenAPI generator library which makes RPC (Remote Procedure Call) | ||
| * functions for the Restful API operation. | ||
| * | ||
| * @param document OpenAPI document to migrate | ||
| * @returns Migrated document | ||
| */ | ||
| export function migrate< | ||
@@ -146,2 +162,14 @@ Schema extends IJsonSchema = IJsonSchema, | ||
| ----------------------------------------------------------- */ | ||
| /** | ||
| * OpenAPI document. | ||
| * | ||
| * `OpenApi.IDocument` represents an OpenAPI document of emended OpenAPI v3.1. | ||
| * | ||
| * In other words, `OpenApi.IDocument` is a structure of `swagger.json` file of | ||
| * OpenAPI v3.1 specification, but a little bit shrinked to remove ambiguous and | ||
| * duplicated expressions of OpenAPI v3.1 for the convenience and clarity. | ||
| * | ||
| * @template Schema JSON schema type | ||
| * @template Operation HTTP operation type | ||
| */ | ||
| export interface IDocument< | ||
@@ -151,34 +179,172 @@ Schema extends IJsonSchema = IJsonSchema, | ||
| > { | ||
| /** | ||
| * OpenAPI version number. | ||
| */ | ||
| openapi: `3.1.${number}`; | ||
| /** | ||
| * List of servers that provide the API. | ||
| */ | ||
| servers?: IServer[]; | ||
| /** | ||
| * Information about the API. | ||
| */ | ||
| info?: IDocument.IInfo; | ||
| /** | ||
| * An object to hold reusable data structures. | ||
| * | ||
| * It stores both DTO schemas and security schemes. | ||
| * | ||
| * For reference, `nestia` defines every object and alias types as reusable DTO | ||
| * schemas. The alias type means that defined by `type` keyword in TypeScript. | ||
| */ | ||
| components: IComponents<Schema>; | ||
| /** | ||
| * The available paths and operations for the API. | ||
| * | ||
| * The 1st key is the path, and the 2nd key is the HTTP method. | ||
| */ | ||
| paths?: Record<string, IPath<Schema, Operation>>; | ||
| /** | ||
| * An object to hold Webhooks. | ||
| * | ||
| * Its structure is same with {@link paths}, so that the 1st key is the path, | ||
| * and the 2nd key is the HTTP method. | ||
| */ | ||
| webhooks?: Record<string, IPath<Schema, Operation>>; | ||
| /** | ||
| * A declaration of which security mechanisms can be used across the API. | ||
| * | ||
| * When this property be configured, it would be overwritten in every API routes. | ||
| * | ||
| * For reference, key means the name of security scheme and value means the `scopes`. | ||
| * The `scopes` can be used only when target security scheme is `oauth2` type, | ||
| * especially for {@link ISwaggerSecurityScheme.IOAuth2.IFlow.scopes} property. | ||
| */ | ||
| security?: Record<string, string[]>[]; | ||
| /** | ||
| * List of tag names with description. | ||
| * | ||
| * It is possible to omit this property or skip some tag name even if | ||
| * the tag name is used in the API routes. In that case, the tag name | ||
| * would be displayed (in Swagger-UI) without description. | ||
| */ | ||
| tags?: IDocument.ITag[]; | ||
| /** | ||
| * Flag for indicating this document is emended by `@samchon/openapi`. | ||
| */ | ||
| "x-samchon-emended": true; | ||
| } | ||
| export namespace IDocument { | ||
| /** | ||
| * Information about the API. | ||
| */ | ||
| export interface IInfo { | ||
| /** | ||
| * The title of the API. | ||
| */ | ||
| title: string; | ||
| /** | ||
| * A short summary of the API. | ||
| */ | ||
| summary?: string; | ||
| /** | ||
| * A full description of the API. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * A URL to the Terms of Service for the API. | ||
| */ | ||
| termsOfService?: string; | ||
| /** | ||
| * The contact information for the exposed API. | ||
| */ | ||
| contact?: IContact; | ||
| /** | ||
| * The license information for the exposed API. | ||
| */ | ||
| license?: ILicense; | ||
| /** | ||
| * Version of the API. | ||
| */ | ||
| version: string; | ||
| } | ||
| /** | ||
| * OpenAPI tag information. | ||
| * | ||
| * It is possible to skip composing this structure, even if some | ||
| * tag names are regsitered in the API routes ({@link OpenApi.IOperation.tags}). | ||
| * In that case, the tag name would be displayed in Swagger-UI without | ||
| * description. | ||
| * | ||
| * However, if you want to describe the tag name, you can compose this | ||
| * structure and describe the tag name in the {@link description} property. | ||
| */ | ||
| export interface ITag { | ||
| /** | ||
| * The name of the tag. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * An optional string describing the tag. | ||
| */ | ||
| description?: string; | ||
| } | ||
| /** | ||
| * Contact information for the exposed API. | ||
| */ | ||
| export interface IContact { | ||
| /** | ||
| * The identifying name of the contact person/organization. | ||
| */ | ||
| name?: string; | ||
| /** | ||
| * The URL pointing to the contact information. | ||
| */ | ||
| url?: string; | ||
| /** | ||
| * The email address of the contact person/organization. | ||
| * | ||
| * @format email | ||
| */ | ||
| email?: string; | ||
| } | ||
| /** | ||
| * License information for the exposed API. | ||
| */ | ||
| export interface ILicense { | ||
| /** | ||
| * The license name used for the API. | ||
| */ | ||
| name: string; | ||
| /** | ||
| * Identifier for the license used for the API. | ||
| * | ||
| * example: MIT | ||
| */ | ||
| identifier?: string; | ||
| /** | ||
| * A URL to the license used for the API. | ||
| */ | ||
| url?: string; | ||
@@ -188,11 +354,42 @@ } | ||
| /** | ||
| * The remote server that provides the API. | ||
| */ | ||
| export interface IServer { | ||
| /** | ||
| * A URL to the target host. | ||
| */ | ||
| url: string; | ||
| /** | ||
| * An optional string describing the target server. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * A map between a variable name and its value. | ||
| * | ||
| * When the server {@link url} is a type of template, this property | ||
| * would be utilized to fill the template with actual values. | ||
| */ | ||
| variables?: Record<string, IServer.IVariable>; | ||
| } | ||
| export namespace IServer { | ||
| /** | ||
| * A variable for the server URL template. | ||
| */ | ||
| export interface IVariable { | ||
| /** | ||
| * Default value to use for substitution. | ||
| */ | ||
| default: string; | ||
| /** @minItems 1 */ enum?: string[]; | ||
| /** | ||
| * List of available values for the variable. | ||
| */ | ||
| enum?: string[]; | ||
| /** | ||
| * An optional description for the server variable. | ||
| */ | ||
| description?: string; | ||
@@ -205,24 +402,100 @@ } | ||
| ----------------------------------------------------------- */ | ||
| export type IPath< | ||
| /** | ||
| * Path item. | ||
| * | ||
| * `OpenApi.IPath` represents a path item of emended OpenAPI v3.1, | ||
| * collecting multiple method operations in a signgle path. | ||
| */ | ||
| export interface IPath< | ||
| Schema extends IJsonSchema = IJsonSchema, | ||
| Operation extends IOperation<Schema> = IOperation<Schema>, | ||
| > = { | ||
| > extends Partial<Record<Method, Operation>> { | ||
| /** | ||
| * Servers that provide the path operations. | ||
| */ | ||
| servers?: IServer[]; | ||
| /** | ||
| * Summary of the path. | ||
| */ | ||
| summary?: string; | ||
| /** | ||
| * Description of the path. | ||
| */ | ||
| description?: string; | ||
| } & Partial<Record<Method, Operation>>; | ||
| } | ||
| /** | ||
| * Remote operation info. | ||
| * | ||
| * `OpenApi.IOperation` represents an Restful API operation provided by the | ||
| * remote server. | ||
| */ | ||
| export interface IOperation<Schema extends IJsonSchema = IJsonSchema> { | ||
| /** | ||
| * Unique string used to identify the operation. | ||
| */ | ||
| operationId?: string; | ||
| /** | ||
| * List of parameters that are applicable for this operation. | ||
| */ | ||
| parameters?: IOperation.IParameter<Schema>[]; | ||
| /** | ||
| * The request body applicable for this operation. | ||
| */ | ||
| requestBody?: IOperation.IRequestBody<Schema>; | ||
| /** | ||
| * The list of possible responses as they are returned from executing this | ||
| * operation. Its key is the HTTP status code, and the value is the metadata of | ||
| * the response in the HTTP status code. | ||
| */ | ||
| responses?: Record<string, IOperation.IResponse<Schema>>; | ||
| /** | ||
| * A list of servers providing this API operation. | ||
| */ | ||
| servers?: IServer[]; | ||
| /** | ||
| * A short summary of what the operation does. | ||
| */ | ||
| summary?: string; | ||
| /** | ||
| * A verbose explanation of the operation behavior. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * List of securities and their scopes that are required for execution. | ||
| * | ||
| * When this property be configured, the Restful API operation requires | ||
| * the matched security value for exection. Its key means security key | ||
| * matched with {@link OpenApi.IDocument.security}. | ||
| * | ||
| * The value means scopes required for the security key when the security | ||
| * type is {@link OpenApi.ISecurityScheme.IOAuth2}. Otherwise the target | ||
| * security type is not {@link OpenApi.ISecurityScheme.IOAuth2}, the value | ||
| * would be empty array. | ||
| */ | ||
| security?: Record<string, string[]>[]; | ||
| /** | ||
| * Tags for API documentation control. | ||
| */ | ||
| tags?: string[]; | ||
| /** | ||
| * Flag for indicating this operation is deprecated. | ||
| */ | ||
| deprecated?: boolean; | ||
| } | ||
| export namespace IOperation { | ||
| /** | ||
| * Parameter of the operation. | ||
| */ | ||
| export interface IParameter<Schema extends IJsonSchema = IJsonSchema> { | ||
@@ -236,2 +509,6 @@ name?: string; | ||
| } | ||
| /** | ||
| * Request body of the operation. | ||
| */ | ||
| export interface IRequestBody<Schema extends IJsonSchema = IJsonSchema> { | ||
@@ -243,2 +520,6 @@ description?: string; | ||
| } | ||
| /** | ||
| * Response of the operation. | ||
| */ | ||
| export interface IResponse<Schema extends IJsonSchema = IJsonSchema> { | ||
@@ -251,8 +532,19 @@ content?: IContent<Schema>; | ||
| /** | ||
| * List of content types supported in request/response body. | ||
| */ | ||
| export type IContent<Schema extends IJsonSchema = IJsonSchema> = Partial< | ||
| Record<ContentType, IMediaType<Schema>> | ||
| >; | ||
| /** | ||
| * Media type of a request/response body. | ||
| */ | ||
| export interface IMediaType<Schema extends IJsonSchema = IJsonSchema> { | ||
| schema?: Schema; | ||
| } | ||
| /** | ||
| * List of supported content media types. | ||
| */ | ||
| export type ContentType = | ||
@@ -270,7 +562,42 @@ | "text/plain" | ||
| ----------------------------------------------------------- */ | ||
| /** | ||
| * Reusable components in OpenAPI. | ||
| * | ||
| * A storage of reusable components in OpenAPI document. | ||
| * | ||
| * In other words, it is a storage of named DTO schemas and security schemes. | ||
| */ | ||
| export interface IComponents<Schema extends IJsonSchema = IJsonSchema> { | ||
| /** | ||
| * An object to hold reusable DTO schemas. | ||
| * | ||
| * In other words, a collection of named JSON schemas. | ||
| */ | ||
| schemas?: Record<string, Schema>; | ||
| /** | ||
| * An object to hold reusable security schemes. | ||
| * | ||
| * In other words, a collection of named security schemes. | ||
| */ | ||
| securitySchemes?: Record<string, ISecurityScheme>; | ||
| } | ||
| /** | ||
| * Type schema info. | ||
| * | ||
| * `OpenApi.IJsonSchema` is a type schema info of the OpenAPI. | ||
| * | ||
| * `OpenApi.IJsonSchema` basically follows the JSON schema definition of | ||
| * OpenAPI v3.1, but a little bit shrinked to remove ambiguous and duplicated | ||
| * expressions of OpenAPI v3.1 for the convenience and clarity. | ||
| * | ||
| * - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed} | ||
| * - Resolve nullable property: {@link OpenApiV3_1.IJsonSchema.__ISignificant.nullable} | ||
| * - Array type utilizes only single {@link OpenAPI.IJsonSchema.IArray.items} | ||
| * - Tuple type utilizes only {@link OpenApi.IJsonSchema.ITuple.prefixItems} | ||
| * - Merge {@link OpenApiV3_1.IJsonSchema.IAnyOf} to {@link OpenApi.IJsonSchema.IOneOf} | ||
| * - Merge {@link OpenApiV3_1.IJsonSchema.IRecursiveReference} to {@link OpenApi.IJsonSchema.IReference} | ||
| * - Merge {@link OpenApiV3_1.IJsonSchema.IAllOf} to {@link OpenApi.IJsonSchema.IObject} | ||
| */ | ||
| export type IJsonSchema = | ||
@@ -290,15 +617,70 @@ | IJsonSchema.IConstant | ||
| export namespace IJsonSchema { | ||
| /** | ||
| * Constant value type. | ||
| */ | ||
| export interface IConstant extends __IAttribute { | ||
| /** | ||
| * The constant value. | ||
| */ | ||
| const: boolean | number | string; | ||
| } | ||
| /** | ||
| * Boolean type info. | ||
| */ | ||
| export interface IBoolean extends __ISignificant<"boolean"> { | ||
| /** | ||
| * The default value. | ||
| */ | ||
| default?: boolean; | ||
| } | ||
| /** | ||
| * Integer type info. | ||
| */ | ||
| export interface IInteger extends __ISignificant<"integer"> { | ||
| /** @type int64 */ default?: number; | ||
| /** @type int64 */ minimum?: number; | ||
| /** @type int64 */ maximum?: number; | ||
| /** | ||
| * Default value. | ||
| * | ||
| * @type int64 | ||
| */ | ||
| default?: number; | ||
| /** | ||
| * Minimum value restriction. | ||
| * | ||
| * @type int64 | ||
| */ | ||
| minimum?: number; | ||
| /** | ||
| * Maximum value restriction. | ||
| * | ||
| * @type int64 | ||
| */ | ||
| maximum?: number; | ||
| /** | ||
| * Exclusive minimum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMinimum` value as `number`, {@link OpenApi} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link minimum} property. | ||
| */ | ||
| exclusiveMinimum?: boolean; | ||
| /** | ||
| * Exclusive maximum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMaximum` value as `number`, {@link OpenApi} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link maximum} property. | ||
| */ | ||
| exclusiveMaximum?: boolean; | ||
| /** | ||
| * Multiple of value restriction. | ||
| * | ||
| * @type uint64 | ||
@@ -309,13 +691,62 @@ * @exclusiveMinimum 0 | ||
| } | ||
| /** | ||
| * Number (double) type info. | ||
| */ | ||
| export interface INumber extends __ISignificant<"number"> { | ||
| /** | ||
| * Default value. | ||
| */ | ||
| default?: number; | ||
| /** | ||
| * Minimum value restriction. | ||
| */ | ||
| minimum?: number; | ||
| /** | ||
| * Maximum value restriction. | ||
| */ | ||
| maximum?: number; | ||
| /** | ||
| * Exclusive minimum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMinimum` value as `number`, {@link OpenAiComposer} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link minimum} property. | ||
| */ | ||
| exclusiveMinimum?: boolean; | ||
| /** | ||
| * Exclusive maximum value restriction. | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined the `exclusiveMaximum` value as `number`, {@link OpenAiComposer} | ||
| * forcibly converts it to `boolean` type, and assign the numeric value to | ||
| * the {@link maximum} property. | ||
| */ | ||
| exclusiveMaximum?: boolean; | ||
| /** @exclusiveMinimum 0 */ multipleOf?: number; | ||
| /** | ||
| * Multiple of value restriction. | ||
| * | ||
| * @exclusiveMinimum 0 | ||
| */ | ||
| multipleOf?: number; | ||
| } | ||
| /** | ||
| * String type info. | ||
| */ | ||
| export interface IString extends __ISignificant<"string"> { | ||
| contentMediaType?: string; | ||
| /** | ||
| * Default value. | ||
| */ | ||
| default?: string; | ||
| /** | ||
| * Format restriction. | ||
| */ | ||
| format?: | ||
@@ -346,47 +777,272 @@ | "binary" | ||
| | (string & {}); | ||
| /** | ||
| * Pattern restriction. | ||
| */ | ||
| pattern?: string; | ||
| /** @type uint64 */ minLength?: number; | ||
| /** @type uint64 */ maxLength?: number; | ||
| /** | ||
| * Content media type restriction. | ||
| */ | ||
| contentMediaType?: string; | ||
| /** | ||
| * Minimum length restriction. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| minLength?: number; | ||
| /** | ||
| * Maximum length restriction. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| maxLength?: number; | ||
| } | ||
| /** | ||
| * Array type. | ||
| */ | ||
| export interface IArray<Schema extends IJsonSchema = IJsonSchema> | ||
| extends __ISignificant<"array"> { | ||
| /** | ||
| * Items type info. | ||
| * | ||
| * The `items` means the type of the array elements. In other words, it is | ||
| * the type schema info of the `T` in the TypeScript array type `Array<T>`. | ||
| */ | ||
| items: Schema; | ||
| /** | ||
| * Unique items restriction. | ||
| * | ||
| * If this property value is `true`, target array must have unique items. | ||
| */ | ||
| uniqueItems?: boolean; | ||
| /** @type uint64 */ minItems?: number; | ||
| /** @type uint64 */ maxItems?: number; | ||
| /** | ||
| * Minimum items restriction. | ||
| * | ||
| * Restriction of minumum number of items in the array. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| minItems?: number; | ||
| /** | ||
| * Maximum items restriction. | ||
| * | ||
| * Restriction of maximum number of items in the array. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| maxItems?: number; | ||
| } | ||
| /** | ||
| * Tuple type info. | ||
| */ | ||
| export interface ITuple<Schema extends IJsonSchema = IJsonSchema> | ||
| extends __ISignificant<"array"> { | ||
| /** | ||
| * Prefix items. | ||
| * | ||
| * The `prefixItems` means the type schema info of the prefix items in the | ||
| * tuple type. In the TypeScript, it is expressed as `[T1, T2]`. | ||
| * | ||
| * If you want to express `[T1, T2, ...TO[]]` type, you can configure the | ||
| * `...TO[]` through the {@link additionalItems} property. | ||
| */ | ||
| prefixItems: Schema[]; | ||
| /** | ||
| * Additional items. | ||
| * | ||
| * The `additionalItems` means the type schema info of the additional items | ||
| * after the {@link prefixItems}. In the TypeScript, if there's a type | ||
| * `[T1, T2, ...TO[]]`, the `...TO[]` is represented by the `additionalItems`. | ||
| * | ||
| * By the way, if you configure the `additionalItems` as `true`, it means | ||
| * the additional items are not restricted. They can be any type, so that | ||
| * it is equivalent to the TypeScript type `[T1, T2, ...any[]]`. | ||
| * | ||
| * Otherwise configure the `additionalItems` as the {@link IJsonSchema}, | ||
| * it means the additional items must follow the type schema info. | ||
| * Therefore, it is equivalent to the TypeScript type `[T1, T2, ...TO[]]`. | ||
| */ | ||
| additionalItems?: boolean | Schema; | ||
| /** | ||
| * Unique items restriction. | ||
| * | ||
| * If this property value is `true`, target tuple must have unique items. | ||
| */ | ||
| uniqueItems?: boolean; | ||
| /** @type uint64 */ minItems?: number; | ||
| /** @type uint64 */ maxItems?: number; | ||
| /** | ||
| * Minimum items restriction. | ||
| * | ||
| * Restriction of minumum number of items in the tuple. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| minItems?: number; | ||
| /** | ||
| * Maximum items restriction. | ||
| * | ||
| * Restriction of maximum number of items in the tuple. | ||
| * | ||
| * @type uint64 | ||
| */ | ||
| maxItems?: number; | ||
| } | ||
| /** | ||
| * Object type info. | ||
| */ | ||
| export interface IObject<Schema extends IJsonSchema = IJsonSchema> | ||
| extends __ISignificant<"object"> { | ||
| /** | ||
| * Properties of the object. | ||
| * | ||
| * The `properties` means a list of key-value pairs of the object's | ||
| * regular properties. The key is the name of the regular property, | ||
| * and the value is the type schema info. | ||
| * | ||
| * If you need additional properties that is represented by dynamic key, | ||
| * you can use the {@link additionalProperties} instead. | ||
| */ | ||
| properties?: Record<string, Schema>; | ||
| /** | ||
| * Additional properties' info. | ||
| * | ||
| * The `additionalProperties` means the type schema info of the additional | ||
| * properties that are not listed in the {@link properties}. | ||
| * | ||
| * If the value is `true`, it means that the additional properties are not | ||
| * restricted. They can be any type. Otherwise, if the value is | ||
| * {@link IOpenAiSchema} type, it means that the additional properties must | ||
| * follow the type schema info. | ||
| * | ||
| * - `true`: `Record<string, any>` | ||
| * - `IOpenAiSchema`: `Record<string, T>` | ||
| */ | ||
| additionalProperties?: boolean | Schema; | ||
| /** | ||
| * List of key values of the required properties. | ||
| * | ||
| * The `required` means a list of the key values of the required | ||
| * {@link properties}. If some property key is not listed in the `required` | ||
| * list, it means that property is optional. Otherwise some property key | ||
| * exists in the `required` list, it means that the property must be filled. | ||
| * | ||
| * Below is an example of the {@link properties} and `required`. | ||
| * | ||
| * ```typescript | ||
| * interface SomeObject { | ||
| * id: string; | ||
| * email: string; | ||
| * name?: string; | ||
| * } | ||
| * ``` | ||
| * | ||
| * As you can see, `id` and `email` {@link properties} are {@link required}, | ||
| * so that they are listed in the `required` list. | ||
| * | ||
| * ```json | ||
| * { | ||
| * "type": "object", | ||
| * "properties": { | ||
| * "id": { "type": "string" }, | ||
| * "email": { "type": "string" }, | ||
| * "name": { "type": "string" } | ||
| * }, | ||
| * "required": ["id", "email"] | ||
| * } | ||
| * ``` | ||
| */ | ||
| required?: string[]; | ||
| } | ||
| /** | ||
| * Reference type directing named schema. | ||
| */ | ||
| export interface IReference<Key = string> extends __IAttribute { | ||
| /** | ||
| * Reference to the named schema. | ||
| * | ||
| * The `ref` is a reference to the named schema. Format of the `$ref` is | ||
| * following the JSON Pointer specification. In the OpenAPI, the `$ref` | ||
| * starts with `#/components/schemas/` which means the type is stored in | ||
| * the {@link OpenApi.IComponents.schemas} object. | ||
| * | ||
| * - `#/components/schemas/SomeObject` | ||
| * - `#/components/schemas/AnotherObject` | ||
| */ | ||
| $ref: Key; | ||
| } | ||
| /** | ||
| * Union type. | ||
| * | ||
| * IOneOf` represents an union type of the TypeScript (`A | B | C`). | ||
| * | ||
| * For reference, even though your Swagger (or OpenAPI) document has | ||
| * defined `anyOf` instead of the `oneOf`, {@link OpenApi} forcibly | ||
| * converts it to `oneOf` type. | ||
| */ | ||
| export interface IOneOf<Schema extends IJsonSchema = IJsonSchema> | ||
| extends __IAttribute { | ||
| oneOf: Exclude<IJsonSchema, IJsonSchema.IOneOf>[]; | ||
| /** | ||
| * List of the union types. | ||
| */ | ||
| oneOf: Exclude<Schema, IJsonSchema.IOneOf>[]; | ||
| } | ||
| /** | ||
| * Null type. | ||
| */ | ||
| export interface INull extends __ISignificant<"null"> {} | ||
| /** | ||
| * Unknown, `any` type. | ||
| */ | ||
| export interface IUnknown extends __IAttribute { | ||
| /** | ||
| * Type is never be defined. | ||
| */ | ||
| type?: undefined; | ||
| } | ||
| /** | ||
| * Significant attributes that can be applied to the most types. | ||
| */ | ||
| export interface __ISignificant<Type extends string> extends __IAttribute { | ||
| /** | ||
| * Discriminator value of the type. | ||
| */ | ||
| type: Type; | ||
| } | ||
| /** | ||
| * Common attributes that can be applied to all types. | ||
| */ | ||
| export interface __IAttribute { | ||
| /** | ||
| * Title of the schema. | ||
| */ | ||
| title?: string; | ||
| /** | ||
| * Detailed description of the schema. | ||
| */ | ||
| description?: string; | ||
| /** | ||
| * Whether the type is deprecated or not. | ||
| */ | ||
| deprecated?: boolean; | ||
@@ -396,2 +1052,11 @@ } | ||
| /** | ||
| * Security scheme of Swagger Documents. | ||
| * | ||
| * `OpenApi.ISecurityScheme` is a data structure representing content of | ||
| * `securitySchemes` in `swagger.json` file. It is composed with 5 types of | ||
| * security schemes as an union type like below. | ||
| * | ||
| * @reference https://swagger.io/specification/#security-scheme-object | ||
| */ | ||
| export type ISecurityScheme = | ||
@@ -404,2 +1069,5 @@ | ISecurityScheme.IApiKey | ||
| export namespace ISecurityScheme { | ||
| /** | ||
| * Normal API key type. | ||
| */ | ||
| export interface IApiKey { | ||
@@ -411,2 +1079,6 @@ type: "apiKey"; | ||
| } | ||
| /** | ||
| * HTTP basic authentication type. | ||
| */ | ||
| export interface IHttpBasic { | ||
@@ -417,2 +1089,6 @@ type: "http"; | ||
| } | ||
| /** | ||
| * HTTP bearer authentication type. | ||
| */ | ||
| export interface IHttpBearer { | ||
@@ -424,2 +1100,6 @@ type: "http"; | ||
| } | ||
| /** | ||
| * OAuth2 authentication type. | ||
| */ | ||
| export interface IOAuth2 { | ||
@@ -426,0 +1106,0 @@ type: "oauth2"; |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by12.94%
357553
- Lines of code
- increased by17.03%
9087
Worsened metrics
- Dev dependency count
- increased by12.5%
9
No dependency changes