JSPM

@samchon/openapi

0.4.5
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 149444
  • Score
    100M100P100Q165336F
  • License MIT

OpenAPI definitions and converters for 'typia' and 'nestia'.

Package Exports

  • @samchon/openapi
  • @samchon/openapi/lib/index.js
  • @samchon/openapi/lib/index.mjs
  • @samchon/openapi/lib/internal/OpenApiTypeChecker
  • @samchon/openapi/lib/internal/OpenApiTypeChecker.js
  • @samchon/openapi/lib/internal/OpenApiV3Downgrader
  • @samchon/openapi/lib/internal/OpenApiV3Downgrader.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@samchon/openapi) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@samchon/openapi

Nestia Editor

GitHub license npm version Downloads Build Status

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/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 to OpenApi.IOperation.parameters
    • Resolve references of OpenApiV3_1.IOperation members
    • Escape references of OpenApiV3_1.IComponents.examples
  • JSON Schema
    • Decompose mixed type: OpenApiV3_1.IJsonSchema.IMixed
    • Resolve 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 to OpenApi.IJsonSchema.IOneOf
    • Merge OpenApiV3_1.IJsonSchema.IRecursiveReference to OpenApi.IJsonSchema.IReference
    • Merge OpenApiV3_1.IJsonSchema.IAllOf to OpenApi.IJsonSchema.IObject

Additionally, @samchon/openapi provides IMigrateDocument for OpenAPI generators. If you're developing TypeScript, @nestia/editor would be the best project utilizing the IMigrateDocument for the OpenAPI SDK generation. Otherwise, you wanna utilize OpenAPI document for OpenAI function calling, @wrtnio/openai-function-schema has been prepared for you.

How to use

npm install @samchon/openapi
import {
  OpenApi,
  SwaggerV2,
  OpenApiV3,
  OpenApiV3_1,
  IMigrateDocument,
} 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");

// also helps openapi generator libraries
const migrate: IMigrateDocument = OpenApi.migrate(output);