OpenAPI definitions and converters (for typia and nestia).
@samchon/openapi
is a collection of OpenAPI definitions of below versions. Those type definitions does not contain every properties of OpenAPI specification, but just have only some features essentially required for typia
and nestia
(especially @nestia/editor
).
Also, @samchon/openapi
provides emended OpenAPI v3.1 definition and its converter/inverter from above versions for convenient development. The keyword "emended" means that OpenApi
is not a direct OpenAPI v3.1 specification (OpenApiV3_1), but a little bit shrinked to remove ambiguous and duplicated expressions of OpenAPI v3.1 for the convenience of typia and nestia
For example, when representing nullable type, OpenAPI v3.1 supports three ways. In that case, OpenApi remains only the third way, so that makes typia
and nestia
(especially @nestia/editor
) to be simple and easy to implement.
{ 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
toOpenApi.IOperation.parameters
- Resolved references of
OpenApiV3_1.IOperation
mebers
- Merge
- JSON Schema
- Decompose mixed type:
OpenApiV3_1.IJsonSchema.IMixed
- Resolved 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
toOpenApi.IJsonSchema.IOneOf
- Merge
OpenApiV3_1.IJsonSchema.IRecursiveReference
toOpenApi.IJsonSchema.IReference
- Merge
OpenApiV3_1.IJsonSchema.IAllOf
toOpenApi.IJsonSchema.IObject
- Decompose mixed type:
npm install @samchon/openapi
import { OpenApi, SwaggerV2, OpenApiV3, OpenApiV3_1 } from "@samchon/openapi";
// original Swagger/OpenAPI document
const input:
| SwaggerV2.IDocument
| OpenApiV3.IDocument
| OpenApiV3_1.IDocument
| OpenApi.IDocument = { ... };
// you can convert it to emended OpenAPI v3.1
const output: OpenApi.IDocument = OpenApi.convert(input);
// it is possible to downgrade to Swagger v2 or OpenAPI v3
const v2: SwaggerV2 = OpenApi.downgrade(output, "2.0");
const v3: OpenApiV3 = OpenApi.downgrade(output, "3.0");
// you can utilize it like below
OpenApi.downgrade(OpenApi.convert(v2), "3.0");
OpenApi.downgrade(OpenApi.convert(v3), "2.0");
-
typia
: https://github.com/samchon/typia -
nestia
: https://github.com/samchon/nestia -
@nestia/editor
: https://nestia.io/docs/editor