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:
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");
Why I have made @samchon/openapi
?
typia
import typia, { tags } from "typia";
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 namespace OpenApi {
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
@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.
What's your thoughts?
Please Register or Login to your account to be able to submit your comment.