{"id":18825010,"url":"https://github.com/lulusir/clean-js-api-gen","last_synced_at":"2025-04-14T01:31:20.059Z","repository":{"id":64364154,"uuid":"566315402","full_name":"lulusir/clean-js-api-gen","owner":"lulusir","description":"Automatically generate request codes according to YAPI, swagger2, swagger3, openapi and other protocols","archived":false,"fork":false,"pushed_at":"2024-04-26T12:21:14.000Z","size":1220,"stargazers_count":25,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T15:48:48.246Z","etag":null,"topics":["axios","code-generator","http-client","openapi","swagger","typescript","ya-pi","yapi"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/lulusir.png","metadata":{"files":{"readme":"README-zh.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-15T12:20:05.000Z","updated_at":"2024-06-07T22:11:15.000Z","dependencies_parsed_at":"2024-04-26T13:35:51.114Z","dependency_job_id":null,"html_url":"https://github.com/lulusir/clean-js-api-gen","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lulusir%2Fclean-js-api-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lulusir%2Fclean-js-api-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lulusir%2Fclean-js-api-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lulusir%2Fclean-js-api-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lulusir","download_url":"https://codeload.github.com/lulusir/clean-js-api-gen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248807540,"owners_count":21164703,"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":["axios","code-generator","http-client","openapi","swagger","typescript","ya-pi","yapi"],"created_at":"2024-11-08T00:58:10.056Z","updated_at":"2025-04-14T01:31:19.604Z","avatar_url":"https://github.com/lulusir.png","language":"TypeScript","readme":"[文档](https://lulusir.github.io/clean-js/api-gen/usage)\n# API 代码生成\n## install \n```\nnpm install @clean-js/api-gen\n```\n## 功能\n - 根据YAPI，swagger2，swagger3等api协议自动生成请求代码\n - 声明完整的Typescript入参和出参类型 \n - 支持路径参数替换\n - YAPI会在注释中写入该接口的地址\n - 方法命名规则为 method+url；如/user，method：post，生成的代码如下\n    ```typescript\n        /** Yapi link: https://yapi.xxxx.com/project/2055/interface/api/125352 */\n    export function postUser(parameter: { body: PostUserBody }) {\n      return Req.request\u003cResponsePostUser\u003e({\n        url: '/user',\n        method: 'post',\n        data: parameter.body,\n      });\n    }\n    ```\n- axios 生成代码如下\n    ```typescript\n    export function postDatasetVersionRecords(\n      parameter: {\n        body: any;\n        path: {\n          version: string;\n          dataset: string;\n        };\n      },\n      config?: AxiosRequestConfig,\n    ) {\n      return Req.request\u003cResponsePostDatasetVersionRecords\u003e({\n        url: replaceUrlPath('/{dataset}/{version}/records', parameter?.path),\n        method: 'post',\n        data: parameter.body,\n        ...config,\n      });\n    }\n    ```\n## config \ninterface\n```typescript\nexport interface Config {\n  url: string; // http或者文件绝对路径\n  outDir?: string; // 输出文件路径，默认为./clean-js\n  type?: \"umi3\" | \"axios\"; // 生成的代码类型，umi3是基于umi-request请求库,  默认为 axios\n  zod?: boolean; // 是否开启zod校验, 用于运行时校验数据类型\n}\n```\n新建clean.config.ts\n```typescript\nexport default {\n  url: 'https://petstore3.swagger.io/api/v3/openapi.json', // swagger 3\n  url: 'https://petstore.swagger.io/v2/swagger.json', // swagger 2\n  url: 'http://yapi.smart-xwork.cn/api/open/plugin/export-full?type=json\u0026pid=186904\u0026status=all\u0026token=59ecff7d43926c3be48f893deba401407f0d819c6c24a99b307a78c0877bc7d2' // yapi\n}\n```\n## YAPI\n1. 项目-\u003e设置-\u003e生成 ts services ![image](./images/yapi-url.png)\n2. 复制remoteUrl地址\n3. 在clean.config.ts文件中填入url地址\n4. 运行npm run api-gen\n\n## Swagger\n1. 复制swagger json在线地址，或者本地文件绝对地址（相对地址）\n2. 在clean.config.ts文件中填入url地址\n3. 运行npm run api-gen\n\n\n## 运行时\n\n在代码运行时设置请求实例\n```typescript\nimport { Req } from '@/clean-js/http.service';\nfunction initCleanJsApi() {\n  Req.set(request);\n}\n```\n\n## Diff\n当文档发生变化，重新运行api-gen会生成diff记录,格式如下，记录新增，减少，变更多少api\n```\nDate: 2022-11-26 12:26:34\n\nSum-up: Added 20 APIs Reduce 3 APIs \n```\n\n\n## 运行时类型校验\n开启zod，可以用于接口返回数据的类型校验，发现线上问题\n在config文件中开启zod即可\n\n```typescript\nexport default {\n  ...\n  zod: true\n}\n```\n配置错误处理函数\n```typescript\nimport { Req } from '@/clean-js/http.service';\n\nReq.setZodErrorHandler((error, value, url, schema ) =\u003e {\n    // 你可以在这里上报错误\n    console.log(error)\n});\n\n```\n## mock\n依赖于worker-webserver的功能，我们可以使用Service Worker来模拟接口请求。具体步骤如下：\n\n1. 安装依赖项：\n\n```bash\nnpm install worker-webserver @anatine/zod-mock @faker-js/faker --save\n```\n2. 使用CLI命令导出sw.js文件，并将其放置在静态资源目录中。如果你正在使用Vite或Umi，对应的目录是public文件夹：\n\n```bash\n\nnpx worker-webserver --out public\n```\n\n3. 启用API-gen的mock功能\n\n  ```typescript\n  // ./clean.config.ts\n  import { defineConfig } from './src/config';\n\n  export default defineConfig({\n    zod: true,\n    url: 'https://petstore3.swagger.io/api/v3/openapi.json', // swagger 3\n    type: 'umi3',\n    mock: {}, // default false\n  });\n\n  ```\n4. 在你的业务代码中你可以通过include和exclude来筛选需要的路由：\n  ```typescript\n  import { apiRoutes, includePath } from \"./api/http.mock\"; // 生成的文件\n   let routes = includePath(apiRoutes, [\"/api/*\"]);\n   routes = excludePath(routes, [\"/api/test/*\"]);\n  ```\n\n4. 在你的业务代码中开启worker服务器：\n  ```typescript\n    import { App, Route } from \"worker-webserver\";\n    import { apiRoutes, includePath } from \"./api/http.mock\"; // 生成的文件\n\n    function openMock() {\n      const app = new App();\n      app.addRoutes(apiRoutes);\n      \n      // 添加服务的中间件，以下功能为统一业务code为200\n      app.use(async (ctx, next) =\u003e {\n        await next();\n      \n        // unified code to 200\n        if (ctx.res.body) {\n          const contentType = ctx.res.headers.get(\"content-type\");\n          if (contentType === \"application/json\") {\n            try {\n              const body = JSON.parse(ctx.res.body);\n              if (body.code) {\n                body.code = 200;\n              }\n              ctx.res.body = JSON.stringify(body);\n            } catch {}\n          }\n        }\n      });\n      \n      // 启动worker服务器\n      app.start();\n    }\n  ```\n\n5. 如果需要关闭，执行以下命令关闭worker服务器：\n  ```typescript\n    app.stop();\n  ```\n\n这样就可以使用Service Worker来模拟接口请求了。","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flulusir%2Fclean-js-api-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flulusir%2Fclean-js-api-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flulusir%2Fclean-js-api-gen/lists"}