@samchon/openapi

@samchon/openapi

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).

1. Swagger v2.0
2. OpenAPI v3.0
3. OpenAPI v3.1

Also, @samchon/openapi provides emended OpenAPI v3.1 definition and its converter 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
  • Merged OpenApiV3_1.IPathItem.parameters to OpenApi.IOperation.parameters
  • Resolved references of OpenApiV3_1.IOperation mebers
• JSON Schema
  • Decomposed 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
  • Merged OpenApiV3_1.IJsonSchema.IAnyOf to OpenApi.IJsonSchema.IOneOf
  • Merged OpenApiV3_1.IJsonSchema.IRecursiveReference to OpenApi.IJsonSchema.IReference

How to use

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);

Related Projects

• typia: https://github.com/samchon/typia
• nestia: https://github.com/samchon/nestia
• @nestia/editor: https://nestia.io/docs/editor