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.
Top comments (2)
Not sure why would you need to validate types tho, don't you trust the server that supplies you with the swagger/openapi json schema? If you do trust it - you probably just need the official typescript generator tool, I think it's pretty good, even supports enums, etc.
Anyway, this does look like an interesting work, I'm just not totally getting the use case.
To make OpenAPI related library, need exact schema info. It is the 1st reason. Also, I'm making a type of OpenAPI generator/converter, so that exact type is much important. Those things are another problem whether trust other libraries' generated OpenAPI document or not.
If you visit and experience one of my link in the article, you may easily understand:
@nestia/editor, a type of OpenAPI generator/convertertypia's JSON schema generator from TypeScript type