{"id":21618678,"url":"https://github.com/shixianqin/autoapi","last_synced_at":"2025-05-07T00:26:36.745Z","repository":{"id":264430053,"uuid":"868496353","full_name":"shixianqin/autoapi","owner":"shixianqin","description":"AutoAPI is a tool based on OpenAPI / Swagger documents to automatically generate atomic request methods and TypeScript types.","archived":false,"fork":false,"pushed_at":"2025-02-28T06:15:32.000Z","size":2612,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T04:26:56.555Z","etag":null,"topics":["autoapi","autogenerated-api","openapi","swagger"],"latest_commit_sha":null,"homepage":"","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/shixianqin.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"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-10-06T14:33:47.000Z","updated_at":"2025-03-23T15:25:43.000Z","dependencies_parsed_at":"2024-11-24T09:15:44.908Z","dependency_job_id":"942c0adb-a159-4e41-96ba-d6e2e9d9e6fe","html_url":"https://github.com/shixianqin/autoapi","commit_stats":null,"previous_names":["shixianqin/autoapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shixianqin%2Fautoapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shixianqin%2Fautoapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shixianqin%2Fautoapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shixianqin%2Fautoapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shixianqin","download_url":"https://codeload.github.com/shixianqin/autoapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251895493,"owners_count":21661348,"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":["autoapi","autogenerated-api","openapi","swagger"],"created_at":"2024-11-24T23:06:29.440Z","updated_at":"2025-05-07T00:26:36.722Z","avatar_url":"https://github.com/shixianqin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AutoAPI\n\nAutoAPI 是一个基于 [OpenAPI](https://www.openapis.org/) / [Swagger](https://swagger.io/) 文档自动生成原子化请求方法和\nTypeScript 类型的工具。\n\n简体中文 | [English](./README.md)\n\n## 特性\n\n+ **原子化请求方法**：独立且随处调用，并利于摇树优化\n+ **自动生成类型**：无需手动维护，自动生成参数类型和响应类型，彻底摆脱参照文档书写类型的烦恼，并减少遗漏和出错的可能性\n+ **类型推断**：就是可以将 JSON 数据转换为 TypeScript 类型。假如没有文档，或者文档中缺少结构定义，那么你就可以通过配置手动请求将响应的数据转换为响应类型\n+ **精细化控制**：灵活配置过滤、分组、命名规则、类型结构等生成细节\n+ **适配器机制**：使用自定义适配器以适应不同的业务场景\n+ **支持 SSR**：可在服务端渲染时可传递上下文参数，需手动在适配器中添加参数透传的逻辑\n+ **优秀的 [API 结构](#api-结构) 管理**：支持多文档、多分组\n\n## 要求\n\n+ 需具备 [OpenAPI](https://www.openapis.org/) / [Swagger](https://swagger.io/) 文档，或者手动声明 API\n+ 需在项目中使用 [TypeScript](https://www.typescriptlang.org/)\n+ 需自行实现 [适配器](#适配器) 逻辑。放心，这很容易\n\n## 安装\n\n\u003cdetails open\u003e\n\u003csummary\u003enpm\u003c/summary\u003e\n\n```shell\nnpm install -D @autoapi/cli\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003epnpm\u003c/summary\u003e\n\n```shell\npnpm add -D @autoapi/cli\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eyarn\u003c/summary\u003e\n\n```shell\nyarn add -D @autoapi/cli\n```\n\n\u003c/details\u003e\n\n## 使用\n\n### 初始化\n\n```shell\nnpx autoapi --init\n```\n\n执行初始化后，会生成一个 `.autoapi` 目录，其中包含配置文件 `config.ts`\n\n### 配置示例\n\n```ts\n// .autoapi/config.ts\n\nimport { defineConfig } from '@autoapi/cli'\n\nexport default defineConfig({\n  docs: [\n    {\n      namespace: 'Example',\n      adapter: '/path/to/your/adapter.ts',\n      source: 'https://api.example.com/autoapi.json' // or YAML\n    },\n\n    // More ...\n  ]\n})\n```\n\n### 构建命令\n\n#### 构建全部文档\n\n```shell\nnpx autoapi\n```\n\n#### 构建指定文档\n\n```shell\nnpx autoapi -n Foo Bar Baz\n```\n\n## 配置\n\nAutoAPI 配置文件放在 `.autoapi` 目录下，可以命名为以下任意名称：\n\n+ `config.ts`（首选，我们在内部使用 [tsx](https://tsx.is/) 执行）\n+ `config.js`\n+ `config.cjs`\n+ `config.mjs`\n+ `config.json`\n\n[查看配置文档 →](./docs/configuration-zh.md)\n\n[查看配置示例 →](examples/.autoapi)\n\n## 适配器\n\n实现一个基于 [Axios](https://axios-http.com/) 的基础适配器：\n\n```ts \nimport { RequestOptions } from '@autoapi/cli'\nimport axios from 'axios'\n\nconst instance = axios.create({\n  baseURL: 'https://api.example.com'\n})\n\n/**\n * 获取 body 数据\n * @param options\n */\nfunction getBodyData (options: RequestOptions) {\n  const { formData, body } = options\n\n  /**\n   * 如果存在 `formData` 参数，说明要发送表单数据，需要将其转换为 `new FormData()` 实例\n   * `formData` 选项是专门为简化传递表单数据设计的\n   * 它和传递 `body` 并将 `Content-Type` 设置为 `multipart/form-data` 是一致的\n   */\n  if (formData) {\n    const form = new FormData()\n    for (const key in formData) {\n      form.append(key, formData[key])\n    }\n    return form\n  }\n\n  /**\n   * 你可以在这里根据 `Content-Type` 来做各种 body 数据的转换，\n   * 如 `text/xml`, `application/x-www-form-urlencoded` 等\n   */\n  // switch (options.headers['Content-Type']) {\n  //   // case 'multipart/form-data':\n  //   // case 'text/xml':\n  // }\n\n  return body\n}\n\n/**\n * 请求适配器\n * 必须导出一个名为 `request` 的函数\n * @param method 请求方法\n * @param path 请求路径\n * @param options 请求选项\n */\nexport function request\u003cT\u003e (method: string, path: string, options: RequestOptions) {\n  if (options.context) {\n    // 如果项目中使用 SSR，并且存在上下文参数时，可在这里处理参数透传的逻辑\n  }\n\n  return instance.request\u003cT\u003e({\n    ...options.config,\n    method,\n    url: path,\n    params: options.queryParams,\n    data: getBodyData(options),\n  })\n}\n```\n\n## API 结构\n\n### 文件目录\n\n```mermaid\nflowchart LR\n    apis[\"apis\"] --\u003e documents@{ shape: docs, label: \"[documents]\" }\ndocuments --\u003e tags@{ shape: procs, label: \"[tags]\" }\ndocuments --\u003e schemas@{ shape: braces, label: \"schemas.d.ts\" }\ntags --\u003e index@{ shape: braces, label: \"index.ts\" }\ntags --\u003e types@{ shape: braces, label: \"types.d.ts\" }\n```\n\n### 操作方法\n\n```mermaid\nflowchart\n    Operations@{ shape: procs, label: \"[Operations]\" }\nOperations -.-\u003e request[\"⬆ Request\"]\nrequest --\u003e pathParams\nrequest --\u003e queryParams\nrequest --\u003e headers\nrequest --\u003e formData\nrequest --\u003e body\nrequest --\u003e config\nrequest --\u003e context\nOperations -..-\u003e response[\"⬇ Response\"]\n\nstyle Operations fill: lightpink, stroke: hotpink, color: black\nstyle request fill: lightskyblue, stroke: steelblue, color: black\nstyle response fill: lightgreen, stroke: green, color: black\n```\n\n### 类型声明\n\n```mermaid\nflowchart\n    API[\"declare namespace API\"] --\u003e Documents@{ shape: docs, label: \"[Documents]\" }\nDocuments --\u003e $parameters --\u003e ParameterTypes@{ shape: procs, label: \"[Types]\" }\nDocuments --\u003e $responses --\u003e ResponseTypes@{ shape: procs, label: \"[Types]\" }\nDocuments --\u003e $schemas --\u003e SchemaTypes@{ shape: procs, label: \"[Types]\" }\nDocuments --\u003e ResponseWrapper\nDocuments --\u003e Tag@{ shape: procs, label: \"[Tags]\" } --\u003e Operations@{ shape: procs, label: \"[Operations]\"}\nOperations --\u003e PathParams\nOperations --\u003e QueryParams\nOperations --\u003e Headers\nOperations --\u003e Body\nOperations --\u003e Response\nOperations --\u003e Responses@{ shape: procs, label: \"Responses\" }\n\nstyle Operations fill: lightpink, stroke: hotpink, color: black\n```\n\n### 适配器\n\n```mermaid\nmindmap\n    Adapter((\"Adapter\"))\n        request[\"request\"]\n        RequestConfig[\"RequestConfig\"]\n        RequestContext[\"RequestContext\"]\n```\n\n## 致谢\n\n+ [OpenAPI](https://www.openapis.org/) \u0026 [Swagger](https://swagger.io/) - OpenAPI 规范（前身为 Swagger 规范）是定义\n  RESTful 接口的世界标准。 OAS 使开发人员能够设计出与技术无关的 API 接口，为其 API 的开发和使用奠定基础。\n+ [change-case](https://github.com/blakeembrey/change-case/) - 在 camelCase、PascalCase、Capital\n  Case、snake_case、param-case、CONSTANT_CASE 等大小写之间转换字符串。\n+ [openapi-types](https://github.com/kogosoftwarellc/open-api) - OpenAPI 文档的 TypeScript 类型.\n+ [js-yaml](https://github.com/nodeca/js-yaml/) - JavaScript YAML 解析器和转储器。 速度极快\n+ [node-fetch](https://github.com/node-fetch/node-fetch/) - 将 Fetch API 引入 Node.js 的轻量级模块\n+ [Prettier](https://prettier.io/) - Prettier 是一个固执己见的代码格式化程序\n+ [APIs.guru](https://apis.guru/) - Wikipedia for WEB APIs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshixianqin%2Fautoapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshixianqin%2Fautoapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshixianqin%2Fautoapi/lists"}