Outline
I made OpenAPI type definitions and converter library, @samchon/openapi.
It supports every versions of Swagger/OpenAPI types, and also support converters to each Swagger/OpenAPI versions. For reference, it has a special type “emended OpenAPI v3.1”, and every converters/downgraders intermediates the “emended OpenAPI v3.1” version.
Here is the type definitions of Swagger/OpenAPI specs:
Swagger v2.0
OpenAPI v3.0
OpenAPI v3.1
// 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“);
Why I have made @samchon/openapi?
console.log(typia.json.application<[IGeometry]>());
interface IGeometry {
title: string | null;
position: IPoint<false>;
size: IPoint<true>;
scale: IPoint;
opacity: null | (number & tags.Minimum<0> & tags.Maximum<1>);
}
interface IPoint<Negative extends boolean = false> {
x: Scalar<Negative>;
y: Scalar<Negative>;
z: Scalar<Negative>;
}
type Scalar<Negative extends boolean> =
Negative extends true ? number : number & tags.Minimum<0>;
At first, my library typia has JSON schema generator from TypeScript types. As you know, expression power of TypeScript is extremely wider than other languages, and even greater than JSON schema spec.
Therefore, to make the TypeScript type to JSON schema to work properly, I need very detailed JSON schema’s DTO type definitions. However, most of OpenAPI type definition libraries was not such detailed. They have abused Record<string, any> types too much, and used string type even when clear string literal type be required. Furthermore, have not utilized union type, and just listed up every properties as optional.
This is the 1st reason why I’ve developed @samchon/openapi with detailed JSON schema definition.
export 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;
export namespace IJsonSchema {
export interface IConstant extends __IAttribute {
const: boolean | number | string;
}
export interface INumber extends __ISignificant<“number“> {
default?: number;
minimum?: number;
maximum?: number;
exclusiveMinimum?: boolean;
exclusiveMaximum?: boolean;
/** @exclusiveMinimum 0 */ multipleOf?: number;
}
export interface IString extends __ISignificant<“string“> {
contentMediaType?: string;
default?: string;
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?: string;
/** @type uint64 */ minLength?: number;
/** @type uint64 */ maxLength?: number;
}
}
}
@nestia/editor is one of OpenAPI generator that converts Swagger/OpenAPI documents to NestJS project or SDK (Software Development Kit) library for the client developer (one of RFC solution), including mockup simulator like msw. Also, it provides enhanced Swagger-UI combined with TypeScript editor like above.
By the way, to accomplish the enough OpenAPI generation, @nestia/editor had to support every Swagger/OpenAPI versions. I’ve tried to find proper solution for Swagger/OpenAPI version converter, but all of them had failed to pass my test cases.
Therefore, I’ve made @samchon/openapi to contain Swagger/OpenAPI converters. Also, as Swagger/OpenAPI specs have too much duplicated expression ways, I have decided to make emended OpenAPI spec that erasing duplicated expressions, and composed converters to transit the emended OpenAI spec.
Here is the example projects generated by @nestia/editor and @samchon/openapi with many versions of Swagger/OpenAPI specs. Aren’t they good to see?
BBS (Bullet-in Board System): SDK & Simulator / NestJS Project
Shopping Mall: SDK & Simulator / NestJS Project
Clickhouse: SDK & Simulator / NestJS Project
Fireblocks: SDK & Simulator / NestJS Project
Uber: SDK & Simulator / NestJS Project
아임포트: SDK & Simulator / NestJS Project
토스페이먼츠: SDK & Simulator / NestJS Project
Hope your contribution
Developing @samchon/openapi, I’ve accomplished my goal to fully support typia and nestia libraries. However, it doesn’t mean that @samchon/openapi has fully defined Swagger/OpenAPI types.
I’ve missed many types, properties that are not required in typia and nestia libraries. As those missed features are not essential for Swagger/OpenAPI spec, there may not be big problem for most use cases.
However, lacking of typia and nestia libraries is obvious. If you also need detailed Swagger/OpenAPI spec like me, but you need more detailed types/properties, or found something missed, please take a contribution.
