React/ReactNative + TypeScript 使用后端提供的swagger Json 文件生成service定义

写在前面：

• 在具体的开发中，联调永远都是比较麻烦的事情，尤其是前后端分离之后，后端一般都需要维护一份文档来告诉我们具体的 API 有什么功能，具体的字段信息，这些信息的维护成本还是相当高的。
• 对接接口总是要写很多的service定义，包括service文件、请求参数类型、响应类型等类型定义。这是一个重复劳动的过程，没有任何技术含量且工作量巨大。
• 什么是 Swagger / OpenAPI？
  • OpenAPI规范，也称作OAS，是一种API文档标准。通过 OpenAPI 规范来定义您的 API，您就可以用文档生成工具来展示您的 API，甚至可以使用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码
  • OpenAPI始于 Swagger 规范，Swagger 规范已于2015 年捐赠给Linux 基金会后改名为 OpenAPI，并定义最新的规范为OpenAPI 3.0
  • 本质上你可以理解为OpenAPI是规范，Swagger则是实现规范的工具

主题：

后端提供swagger json文件

• 后端提供swagger Json时，应当以尽量小的颗粒度多次提供，减少生成的servers代码冗余

前端通过解析OpenApi文档结构来生成我们的service文件

目前社区提供的方案了解到以下几种，感兴趣的可以了解更多：

• OpenApi社区开源了OpenApi Generator。https://github.com/openapitools/openapi-generator
• swagger-typescript-api。https://juejin.cn/post/7205198600015003685
• @umijs/openapi

因为react项目使用umi较多，此处建议使用@umijs/openapi，并详细介绍：

• @umijs/openapi 是拆分独立的一个插件，不需要依赖于umi环境也可以使用。
• 如果你使用 umi ，你可以添加@umijs/plugin-openapi 插件。
• 如果你使用 antd Pro / umi Max ，可以直接使用配置开启openapi（非最新版本可能需要手动添加）。https://pro.ant.design/zh-CN/docs/openapi/
• 建议生成的servers进行手动整理目录结构或内容等

一、非umi项目，使用@umijs/openapi。

参考：https://www.npmjs.com/package/@umijs/openapi
1、安装依赖：

npm i @umijs/openapi ts-node -D

2、创建配置：
在根目录下创建openapi.config.ts，添加以下内容：

const {generateService} = require('@umijs/openapi');

generateService({
  // 请求工具路径，按实际项目更改，建议尽量按umi-request的参数格式定义请求工具。因为生成的server传参是按umi-request来的。
  requestLibPath: "import request from '@/utils/request'",
  // 后端提供的swagger Json。ps：这里使用相对路径存在问题，没有解决。使用绝对路径、远程路径可以
  schemaPath: 'E:/workspacePc/CangChu/warehouse_app/oneapi.json',
  // 生成servers的路径
  serversPath: './servers',
  // 项目名称，生成server会在这个文件夹下
  projectName: 'app',
  // 命名空间，生成的类型命名空间
  namespace: 'swagger',
});

3、添加package脚本

{
  "scripts": {
    "openapi": "ts-node openapi.config.ts"
  }
}

4、生成servers

npm run openapi

二、umi、umiMax、ant Pro 项目，使用 @umijs/plugin-openapi 插件。

参考：https://pro.ant.design/zh-CN/docs/openapi/