An OpenAPI document define, generate and schema validation library supported by ajv.
npm install @moontai0724/openapiyarn add @moontai0724/openapipnpm add @moontai0724/openapiYou can define a path by calling the define method.
import OpenAPI, {
type OperationSchemas,
type TransformPathItemOptions,
} from "@moontai0724/openapi";
import Type from "@sinclair/typebox";
const openapi = new OpenAPI({
/** basic document options */
});
const path = "/:path1";
const method = "patch";
const schemas: OperationSchemas = {
body: Type.Object({
body1: Type.String(),
}),
cookie: Type.Object({
cookie1: Type.String(),
}),
header: Type.Object({
header1: Type.String(),
}),
path: Type.Object({
path1: Type.String(),
}),
query: Type.Object({
query1: Type.String(),
}),
response: Type.Object({
response1: Type.String(),
}),
};
const options: TransformPathItemOptions = {
/** options */
};
openapi.define(path, method, schemas, options);For more informations, you can see examples below or the API documentation.
You can get the Ajv instance for further validation when initializing the OpenAPI instance by calling the init method.
import OpenAPI from "@moontai0724/openapi";
const openapi = new OpenAPI({
/** basic document options */
});
const path = "/:id";
const method = "patch";
const schemas: OperationSchemas = {
cookie: {
type: "object",
properties: {
token: {
type: "string",
description: "Token",
},
},
},
path: {
type: "object",
required: ["id"],
properties: {
id: {
type: "number",
},
},
},
response: {
description: "Specific resource",
type: "object",
required: ["success", "message"],
properties: {
success: {
type: "boolean",
},
message: {
type: "string",
},
},
},
};
const options: TransformPathItemOptions = {
/** options */
};
const ajv = openapi.init(path, method, schemas, options); // got the Ajv instance with schemas definedFor more informations, you can see examples below or the API documentation.
You can validate a set of data after defined a path by calling the validate method.
import OpenAPI from "@moontai0724/openapi";
const openapi = new OpenAPI({
/** basic document options */
});
const path = "/:id";
const method = "patch";
const schemas: OperationSchemas = {
/** schemas same as above */
};
openapi.define(path, method, schemas);
const data = {
body: {
body1: "body1",
},
cookie: {
cookie1: "cookie1",
},
header: {},
path: null,
query: undefined,
};
const result = openapi.validate(path, method, data);
/**
* result = {
* body: null,
* cookie: null,
* header: [
* {
* instancePath: "",
* keyword: "required",
* message: "must have required property 'header1'",
* params: {
* missingProperty: "header1",
* },
* schemaPath: "#/required",
* },
* ],
* path: [
* {
* instancePath: "",
* keyword: "type",
* message: "must be object",
* params: {
* type: "object",
* },
* schemaPath: "#/type",
* },
* ],
* query: [
* {
* instancePath: "",
* keyword: "type",
* message: "must be object",
* params: {
* type: "object",
* },
* schemaPath: "#/type",
* },
* ],
* }
*/For more informations, you can see the API documentation.
import OpenAPI from "@moontai0724/openapi";
const openapi = new OpenAPI({
openapi: "3.1.0",
info: {
title: "Example",
version: "1.0.0",
},
});
openapi.define("/:id", "get", {
cookie: {
type: "object",
properties: {
token: {
type: "string",
description: "Token",
},
},
},
path: {
type: "object",
required: ["id"],
properties: {
id: {
type: "number",
},
},
},
response: {
description: "Specific resource",
type: "object",
required: ["success", "message"],
properties: {
success: {
type: "boolean",
},
message: {
type: "string",
},
},
},
});
console.log(openapi.json()); // Generated OpenAPI JSON string.
console.log(openapi.yaml()); // Generated OpenAPI YAML string.Rather than directly defining the JSON schemas in hand, we recommend you to use the TypeBox library to define the schemas. It would be like this:
import { Type } from "@sinclair/typebox";
import OpenAPI from "./src";
const openapi = new OpenAPI({
openapi: "3.1.0",
info: {
title: "Example",
version: "1.0.0",
},
});
openapi.define("/:id", "get", {
cookie: Type.Object({
token: Type.Optional(
Type.String({
description: "Token",
}),
),
}),
path: Type.Object({
id: Type.Number(),
}),
response: Type.Object(
{
success: Type.Boolean(),
message: Type.String(),
},
{ description: "Specific resource" },
),
});
console.log(openapi.json()); // Generated OpenAPI JSON string.
console.log(openapi.yaml()); // Generated OpenAPI YAML string.The above code will generate the following document:
openapi: "3.1.0"
info:
title: "Example"
version: "1.0.0"
paths:
/:id:
get:
parameters:
- name: "token"
in: "cookie"
description: "Token"
required: false
schema:
type: "string"
- name: "id"
in: "path"
required: true
schema:
type: "number"
responses:
200:
description: "Specific resource"
content:
application/json:
schema:
type: "object"
properties:
success:
type: "boolean"
message:
type: "string"
required:
- "success"
- "message"The last parameter is options for transforming the schemas.
There are some options when transforming the schema and also overwrites to the transformed schema.
For example, you can change the response http code or apply schema to specific content types:
/* ... */
openapi.define(
"/",
"post",
{
body: {
type: "object",
properties: {
name: {
type: "string",
},
},
},
},
{
requestBody: {
contentTypes: ["application/json", "application/x-www-form-urlencoded"],
},
responses: {
httpCode: 201,
overwrite: {
default: {
description: "Default Empty Response",
},
},
},
},
);
/* ... */The above code will generate the following document:
openapi: "3.1.0"
info:
title: "Example"
version: "1.0.0"
paths:
/:
post:
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
name:
type: "string"
application/x-www-form-urlencoded:
schema:
type: "object"
properties:
name:
type: "string"
responses:
201:
description: "No Description." # Since the description is required in response, there will set "No Description." if schema has no description.
default:
description: "Default Empty Response"For more informations, you can see the API documentation.