{"id":20858515,"url":"https://github.com/openapi/openapi","last_synced_at":"2026-01-12T06:36:37.832Z","repository":{"id":54398798,"uuid":"315884033","full_name":"openapi/openapi","owner":"openapi","description":"Generate JavaScript or TypeScript code from Swagger/OpenAPI specifications","archived":false,"fork":false,"pushed_at":"2023-01-12T12:13:33.000Z","size":1412,"stargazers_count":68,"open_issues_count":11,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-31T07:49:36.224Z","etag":null,"topics":["openapi"],"latest_commit_sha":null,"homepage":"https://npmjs.com/openapi","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-25T09:05:44.000Z","updated_at":"2024-10-22T08:31:46.000Z","dependencies_parsed_at":"2023-02-09T11:47:22.746Z","dependency_job_id":null,"html_url":"https://github.com/openapi/openapi","commit_stats":null,"previous_names":["openapijs/openapi"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi%2Fopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openapi","download_url":"https://codeload.github.com/openapi/openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225130753,"owners_count":17425506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["openapi"],"created_at":"2024-11-18T04:46:19.914Z","updated_at":"2024-11-18T04:46:20.418Z","avatar_url":"https://github.com/openapi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openapi/openapi\n\nGenerate JavaScript or TypeScript code from Swagger/OpenAPI specification.\n\n## Install\n\n```sh\nnpm install -D openapi\n# or\npnpm add -D openapi\n# or\nyarn add -D openapi\n```\n\n## Examples\n\n```sh\npnpm openapi --file ../src/mocks/local-file-api.json\n# or\npnpm openapi --file ../src/mocks/local-file-api.yaml\n# or\npnpm openapi --file protocol://url/api.json\n```\n\n## Usage CLI\n\n```sh\npnpm openapi [options]\n\nOptions:\n  -V, --version            output the version number\n  --output-dir \u003cpath\u003e      Path output directory js api with types (default: './api')\n  --config \u003cpath\u003e          Path to config\n  --mode \u003ctype\u003e            Mode for additional info: 'prod' | 'dev' (default: 'prod')\n  --file \u003cpath\u003e            Path to file with api (*.json, *.yaml, url)\n  --authorization \u003cvalue\u003e  Auth token for get api by url (it is header for request)\n  --deprecated \u003ctype\u003e      Action for deprecated methods: 'warning' | 'ignore' | 'exception' (default: 'warning')\n  --import-request         Import request code in out code\n  --original-body          Build with original request body\n  --ignore-description     Print description of request\n  -h, --help               display help for command\n```\n\n## Usage config in file\n\nThis package use [`cosmiconfig`](https://github.com/davidtheclark/cosmiconfig) for finding config.\n\n### Config can exist next places\n\n- a `openapi` property in `package.json`\n- a `.openapirc` file in JSON or YAML format\n- a `.openapirc.json` file\n- a `.openapirc.yaml`, `.openapirc.yml`, or `.openapirc.js` file\n- a `openapi.config.js` file exporting a JS object\n\n```js\nmodule.exports = {\n  // Path to file with api (*.json, *.yaml, url)\n  file: \"./swagger-api.json\", // string\n\n  // Api in json (if not use option 'file', more important than path to file)\n  apiJson: { ... },\n\n  // Auth token for get api by url (it is header for request)\n  authorization: \"Token 123qwerty\", // string\n\n  // Path output directory js api with types\n  outputDir: \"./api\", // string (default: \"./api\")\n\n  // Mode for additional info\n  mode: \"prod\", // \"prod\" | \"dev\" (default: \"prod\")\n\n  // Action for deprecated methods\n  deprecated: \"warning\", // \"warning\" | \"ignore\" | \"exception\" (default: \"warning\")\n\n  // Import request code in out code\n  // true — add import from `openapi/request`\n  // false — embed request to `outputDir` and import from it\n  // \"disabled\" — completely disable imporing `request`, use `templateCodeBefore`\n  importRequest: true, // (default: false)\n\n  // Build with original request body\n  originalBody: true, // (default: false)\n\n  // Ignore description of requests\n  ignoreDescription: true, // default: false\n\n  // Completely disable generating types file (.d.ts)\n  disableTypesGenerate: true, // (default: false)\n\n  /**\n   * Change file name for source code\n   * Also it can be a function\n   * @example\n   * templateFileNameCode: ({ swaggerData, changeCase }) =\u003e string,\n   */\n  templateFileNameCode: 'my-api.js', // (default: 'index.js')\n\n  /**\n   * Change file name for typing\n   * Also it can be a function\n   * @example\n   * templateFileNameTypes: ({ swaggerData, changeCase }) =\u003e string,\n   */\n  templateFileNameTypes: 'my-api.d.ts', // (default: 'index.d.js')\n\n  /**\n   * Load presets and merge local properties to it\n   * If preset created as a function, options can be passed\n   * @example\n   * presets: [\n   *  ['my-super-openapi-preset', { passed: 'options' }],\n   *  ['another-openapi-preset', { beautiful: 'options' }],\n   * ]\n   * If no options passed or used simple form, empty object passed to functional preset\n   */\n  presets: ['my-super-openapi-preset'], // (default: [])\n\n  /**\n   * Template before main block code\n   * @param {{\n   *  swaggerData: { info: object; paths: object; components: object; };\n   *  changeCase: { paramCase: Function; camelCase: Function; pascalCase: Function; ... };\n   * }} extra\n   */\n  templateCodeBefore: (extra) =\u003e \"\",\n\n  /**\n   * Template request code\n   * @param {{\n   *  name: string;\n   *  method: string;\n   *  url: string;\n   *  isWarningDeprecated: boolean;\n   *  isExistParams: boolean;\n   *  defaultParams: object;\n   * }} params\n   * @param {{\n   *  swaggerData: { info: object; paths: object; components: object; };\n   *  requestSwaggerData: { operationId: string; requestBody?: object; responses: object };\n   *  changeCase: { paramCase: Function; camelCase: Function; pascalCase: Function; ... };\n   * }} extra\n   */\n  templateRequestCode: (params, extra) =\u003e \"\",\n\n  /**\n   * Template after maon block code\n   * @param {{\n   *  swaggerData: { info: object; paths: object; components: object; };\n   *  changeCase: { paramCase: Function; camelCase: Function; pascalCase: Function; ... };\n   * }} extra\n   */\n  templateCodeAfter: (extra) =\u003e \"\",\n\n  /**\n   * Template before main block types\n   * @param {{\n   *  swaggerData: { info: object; paths: object; components: object; };\n   *  changeCase: { paramCase: Function; camelCase: Function; pascalCase: Function; ... };\n   * }} extra\n   */\n  templateTypesBefore: (extra) =\u003e \"\",\n\n  /**\n   * Template request types\n   * @param {{\n   *  name: string;\n   *  summary: string;\n   *  description: string;\n   *  countVariants: number;\n   *  index: number;\n   *  params: SwaggerData | null;\n   *  addedParams: SwaggerData | null;\n   *  result: SwaggerData | null;\n   * }} params\n   * * @param {{\n   *  swaggerData: { info: object; paths: object; components: object; };\n   *  requestSwaggerData: { operationId: string; requestBody?: object; responses: object };\n   *  changeCase: { paramCase: Function; camelCase: Function; pascalCase: Function; ... };\n   * }} extra\n   *\n   * @type {https://swagger.io/docs/specification/data-models/} SwaggerData\n   */\n  templateRequestTypes: (param, extra) =\u003e \"\",\n\n  /**\n   * Template after main block types\n   * @param {{\n   *  swaggerData: { info: object; paths: object; components: object; };\n   *  changeCase: { paramCase: Function; camelCase: Function; pascalCase: Function; ... };\n   * }} extra\n   */\n  templateTypesAfter: (extra) =\u003e \"\",\n};\n```\n\n## API\n\n```js\nimport { openapiGenerate } from \"openapi\";\n\nconst { code, types } = openapiGenerate({\n  file: \"./swagger-api.json\",\n});\n\nconsole.log(code);\n// =\u003e js code\n\nconsole.log(types);\n// =\u003e typescript types\n```\n\n[More examples](https://github.com/openapi/openapi/tree/next/examples)\n\n## Additional notes\n\n- If you will use this package after application created, you will have problem with generated api,\n  because current api in your app will have different with your swagger api maybe.\n\n## How to create custom preset\n\n1. Create new NPM package (create directory and `npm init` there)\n1. Name your package with `openapi-preset-` prefix (ex.: `openapi-preset-effector`)\n1. Create `index.js` and set `\"main\": \"index.js\"` in your package.json\n1. Fill your `index.js` with any properties from list before\n1. Save and publish\n1. Use it like: `presets: ['openapi-preset-example']`\n\n\u003e Hint: if you want to use local file as a preset, just use `require.resolve`:\n\u003e `presets: [require.resolve('./local-preset')]`\n\u003e It is works only in `.js` configs\n\n### Preset with options\n\n1. Export from your javascript file function with single argument\n1. Add valid options to your README.md\n1. Use nested array form to pass options to preset\n\n#### Example preset with options\n\n```js\nmodule.exports = (options) =\u003e ({\n  templateRequestCode: (request, extra) =\u003e\n    options.parseBody\n      ? generatorWithParser(request, extra)\n      : simpleGenerator(request, extra),\n});\n```\n\nUsage `openapi.config.js`:\n\n```js\nmodule.exports = {\n  file: \"./swagger-api.json\",\n  presets: [\n    [\"openapi-preset-example\", { parseBody: true }],\n    [\n      \"openapi-preset-another\",\n      { requestImport: { module: \"./axios-fabric\", name: \"axios\" } },\n    ],\n  ],\n};\n```\n\n## Tested generation on swagger versions\n\n- 2.0\n- 3.0.1\n- 3.0.2\n\n## Roadmap\n\n- [ ] Struct generated files by tags\n- [ ] Detect `nullable`\n- [ ] Validate by schema\n- [ ] Combine types by\n\n## Development\n\n### How to release a new version\n\n1. Wait for release-drafter to generates a new draft release\n1. All PRs should have correct labels and useful titles. You can [review available labels here](https://github.com/openapi/openapi/blob/master/.github/release-drafter.yml).\n1. Update labels for PRs and titles, next [manually run the release drafter action](https://github.com/openapi/openapi/actions/workflows/release-drafter.yml) to regenerate the draft release.\n1. Review the new version and press \"Publish\"\n1. If required check \"Create discussion for this release\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenapi%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi%2Fopenapi/lists"}