{"id":17357023,"url":"https://github.com/moontai0724/openapi","last_synced_at":"2026-02-28T23:02:20.500Z","repository":{"id":236084341,"uuid":"791806496","full_name":"moontai0724/openapi","owner":"moontai0724","description":"An OpenAPI document define, generate and schema validation library supported by ajv.","archived":false,"fork":false,"pushed_at":"2024-07-08T09:06:56.000Z","size":652,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T06:18:59.494Z","etag":null,"topics":["automation","document","generate","openapi","schema","typebox","typescript","validation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@moontai0724/openapi","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moontai0724.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-25T12:08:51.000Z","updated_at":"2025-01-01T20:29:22.000Z","dependencies_parsed_at":"2024-06-09T19:45:33.238Z","dependency_job_id":"a4941eca-9334-4645-b910-91010c66d585","html_url":"https://github.com/moontai0724/openapi","commit_stats":null,"previous_names":["moontaiworks/openapi","moontai0724/openapi"],"tags_count":3,"template":false,"template_full_name":"moontai0724/package-template","purl":"pkg:github/moontai0724/openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moontai0724%2Fopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moontai0724%2Fopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moontai0724%2Fopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moontai0724%2Fopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moontai0724","download_url":"https://codeload.github.com/moontai0724/openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moontai0724%2Fopenapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29954583,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T22:53:01.873Z","status":"ssl_error","status_checked_at":"2026-02-28T22:52:50.699Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","document","generate","openapi","schema","typebox","typescript","validation"],"created_at":"2024-10-15T18:59:47.485Z","updated_at":"2026-02-28T23:02:20.455Z","avatar_url":"https://github.com/moontai0724.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @moontai0724/openapi\n\n[![NPM Version](https://img.shields.io/npm/v/@moontai0724/openapi)](https://www.npmjs.com/package/@moontai0724/openapi)\n[![NPM Downloads](https://img.shields.io/npm/d18m/@moontai0724/openapi)](https://www.npmjs.com/package/@moontai0724/openapi)\n[![Codecov](https://codecov.io/gh/moontai0724/openapi/graph/badge.svg)](https://codecov.io/gh/moontai0724/openapi)\n\nAn OpenAPI document define, generate and schema validation library supported by ajv.\n\n## 📝 Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n- [Examples](#examples)\n- [API Document](#api-document)\n\n## Install\n\n### NPM\n\n```bash\nnpm install @moontai0724/openapi\n```\n\n### Yarn\n\n```bash\nyarn add @moontai0724/openapi\n```\n\n### PNPM\n\n```bash\npnpm add @moontai0724/openapi\n```\n\n## Usage\n\n### define(path, method, schemas, options)\n\nYou can define a path by calling the `define` method.\n\n```typescript\nimport OpenAPI, {\n  type OperationSchemas,\n  type TransformPathItemOptions,\n} from \"@moontai0724/openapi\";\nimport Type from \"@sinclair/typebox\";\n\nconst openapi = new OpenAPI({\n  /** basic document options */\n});\n\nconst path = \"/:path1\";\nconst method = \"patch\";\nconst schemas: OperationSchemas = {\n  body: Type.Object({\n    body1: Type.String(),\n  }),\n  cookie: Type.Object({\n    cookie1: Type.String(),\n  }),\n  header: Type.Object({\n    header1: Type.String(),\n  }),\n  path: Type.Object({\n    path1: Type.String(),\n  }),\n  query: Type.Object({\n    query1: Type.String(),\n  }),\n  response: Type.Object({\n    response1: Type.String(),\n  }),\n};\nconst options: TransformPathItemOptions = {\n  /** options */\n};\n\nopenapi.define(path, method, schemas, options);\n```\n\nFor more informations, you can see examples below or the [API documentation](https://www.moontai0724.tw/openapi/classes/OpenAPI.html#define).\n\n### init(path, method, schemas, options)\n\nYou can get the Ajv instance for further validation when initializing the OpenAPI instance by calling the `init` method.\n\n```typescript\nimport OpenAPI from \"@moontai0724/openapi\";\n\nconst openapi = new OpenAPI({\n  /** basic document options */\n});\n\nconst path = \"/:id\";\nconst method = \"patch\";\nconst schemas: OperationSchemas = {\n  cookie: {\n    type: \"object\",\n    properties: {\n      token: {\n        type: \"string\",\n        description: \"Token\",\n      },\n    },\n  },\n  path: {\n    type: \"object\",\n    required: [\"id\"],\n    properties: {\n      id: {\n        type: \"number\",\n      },\n    },\n  },\n  response: {\n    description: \"Specific resource\",\n    type: \"object\",\n    required: [\"success\", \"message\"],\n    properties: {\n      success: {\n        type: \"boolean\",\n      },\n      message: {\n        type: \"string\",\n      },\n    },\n  },\n};\nconst options: TransformPathItemOptions = {\n  /** options */\n};\n\nconst ajv = openapi.init(path, method, schemas, options); // got the Ajv instance with schemas defined\n```\n\nFor more informations, you can see examples below or the [API documentation](https://www.moontai0724.tw/openapi/classes/OpenAPI.html#init).\n\n### validate(path, method, data, options)\n\nYou can validate a set of data after defined a path by calling the `validate` method.\n\n```typescript\nimport OpenAPI from \"@moontai0724/openapi\";\n\nconst openapi = new OpenAPI({\n  /** basic document options */\n});\n\nconst path = \"/:id\";\nconst method = \"patch\";\nconst schemas: OperationSchemas = {\n  /** schemas same as above */\n};\n\nopenapi.define(path, method, schemas);\n\nconst data = {\n  body: {\n    body1: \"body1\",\n  },\n  cookie: {\n    cookie1: \"cookie1\",\n  },\n  header: {},\n  path: null,\n  query: undefined,\n};\n\nconst result = openapi.validate(path, method, data);\n/**\n * result = {\n *   body: null,\n *   cookie: null,\n *   header: [\n *     {\n *       instancePath: \"\",\n *       keyword: \"required\",\n *       message: \"must have required property 'header1'\",\n *       params: {\n *         missingProperty: \"header1\",\n *       },\n *       schemaPath: \"#/required\",\n *     },\n *   ],\n *   path: [\n *     {\n *       instancePath: \"\",\n *       keyword: \"type\",\n *       message: \"must be object\",\n *       params: {\n *         type: \"object\",\n *       },\n *       schemaPath: \"#/type\",\n *     },\n *   ],\n *   query: [\n *     {\n *       instancePath: \"\",\n *       keyword: \"type\",\n *       message: \"must be object\",\n *       params: {\n *         type: \"object\",\n *       },\n *       schemaPath: \"#/type\",\n *     },\n *   ],\n * }\n */\n```\n\nFor more informations, you can see the [API documentation](https://www.moontai0724.tw/openapi/classes/OpenAPI.html#validate).\n\n## Examples\n\n### Define a path and generate the document\n\n```typescript\nimport OpenAPI from \"@moontai0724/openapi\";\n\nconst openapi = new OpenAPI({\n  openapi: \"3.1.0\",\n  info: {\n    title: \"Example\",\n    version: \"1.0.0\",\n  },\n});\n\nopenapi.define(\"/:id\", \"get\", {\n  cookie: {\n    type: \"object\",\n    properties: {\n      token: {\n        type: \"string\",\n        description: \"Token\",\n      },\n    },\n  },\n  path: {\n    type: \"object\",\n    required: [\"id\"],\n    properties: {\n      id: {\n        type: \"number\",\n      },\n    },\n  },\n  response: {\n    description: \"Specific resource\",\n    type: \"object\",\n    required: [\"success\", \"message\"],\n    properties: {\n      success: {\n        type: \"boolean\",\n      },\n      message: {\n        type: \"string\",\n      },\n    },\n  },\n});\n\nconsole.log(openapi.json()); // Generated OpenAPI JSON string.\nconsole.log(openapi.yaml()); // Generated OpenAPI YAML string.\n```\n\nRather than directly defining the JSON schemas in hand, we recommend you to use the [TypeBox](https://github.com/sinclairzx81/typebox) library to define the schemas. It would be like this:\n\n```typescript\nimport { Type } from \"@sinclair/typebox\";\n\nimport OpenAPI from \"./src\";\n\nconst openapi = new OpenAPI({\n  openapi: \"3.1.0\",\n  info: {\n    title: \"Example\",\n    version: \"1.0.0\",\n  },\n});\n\nopenapi.define(\"/:id\", \"get\", {\n  cookie: Type.Object({\n    token: Type.Optional(\n      Type.String({\n        description: \"Token\",\n      }),\n    ),\n  }),\n  path: Type.Object({\n    id: Type.Number(),\n  }),\n  response: Type.Object(\n    {\n      success: Type.Boolean(),\n      message: Type.String(),\n    },\n    { description: \"Specific resource\" },\n  ),\n});\n\nconsole.log(openapi.json()); // Generated OpenAPI JSON string.\nconsole.log(openapi.yaml()); // Generated OpenAPI YAML string.\n```\n\nThe above code will generate the following document:\n\n```yaml\nopenapi: \"3.1.0\"\ninfo:\n  title: \"Example\"\n  version: \"1.0.0\"\npaths:\n  /:id:\n    get:\n      parameters:\n        - name: \"token\"\n          in: \"cookie\"\n          description: \"Token\"\n          required: false\n          schema:\n            type: \"string\"\n        - name: \"id\"\n          in: \"path\"\n          required: true\n          schema:\n            type: \"number\"\n      responses:\n        200:\n          description: \"Specific resource\"\n          content:\n            application/json:\n              schema:\n                type: \"object\"\n                properties:\n                  success:\n                    type: \"boolean\"\n                  message:\n                    type: \"string\"\n                required:\n                  - \"success\"\n                  - \"message\"\n```\n\n### Define a path and generate the document with options to adjust or overwrites\n\nThe last parameter is options for transforming the schemas.\n\nThere are some options when transforming the schema and also overwrites to the transformed schema.\n\nFor example, you can change the response http code or apply schema to specific content types:\n\n```typescript\n/* ... */\nopenapi.define(\n  \"/\",\n  \"post\",\n  {\n    body: {\n      type: \"object\",\n      properties: {\n        name: {\n          type: \"string\",\n        },\n      },\n    },\n  },\n  {\n    requestBody: {\n      contentTypes: [\"application/json\", \"application/x-www-form-urlencoded\"],\n    },\n    responses: {\n      httpCode: 201,\n      overwrite: {\n        default: {\n          description: \"Default Empty Response\",\n        },\n      },\n    },\n  },\n);\n/* ... */\n```\n\nThe above code will generate the following document:\n\n```yaml\nopenapi: \"3.1.0\"\ninfo:\n  title: \"Example\"\n  version: \"1.0.0\"\npaths:\n  /:\n    post:\n      parameters: []\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              type: \"object\"\n              properties:\n                name:\n                  type: \"string\"\n          application/x-www-form-urlencoded:\n            schema:\n              type: \"object\"\n              properties:\n                name:\n                  type: \"string\"\n      responses:\n        201:\n          description: \"No Description.\" # Since the description is required in response, there will set \"No Description.\" if schema has no description.\n        default:\n          description: \"Default Empty Response\"\n```\n\n## API Document\n\nFor more informations, you can see the [API documentation](https://moontai0724.github.io/openapi/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoontai0724%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoontai0724%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoontai0724%2Fopenapi/lists"}