使用openapi文档生成请求服务。支持 Openapi 3.0
pnpm add foca-openapi在项目根目录下创建一个名为 openapi.config.ts 的文件
import { defineConfig } from 'foca-openapi'; export default defineConfig({ // 可以是本地路径，也可以是远程地址 url: 'http://domain.com/openapi.json', });指令的作用是把openapi文档转换为前端服务，生成的文件会自动放到 src/openapi 目录
npx openapi使用合适的请求适配器创建好服务后，就可以导出给各个模块使用了
// ./src/openapi/index.ts import { OpenapiClient } from './openapi'; import { fetchAdapter } from 'foca-openapi/adapters/fetch'; const adapter = fetchAdapter({ baseURL: 'http://api.com' }); export const client = new OpenapiClient(adapter); export { OpenapiClient };引入形式 import { xxAdapter } from 'foca-openapi/adapters/xx';
当前已内置多个适配器，可满足大部分需求。如果无法满足项目需求则可以自行创建适配器（或者提issue）
- axios
- fetch
- taro
- uniapp
如果一个项目需要融合多个openapi文档，则可以用数组的形式配置
// openapi.config.ts import { defineConfig } from 'foca-openapi'; export default defineConfig([ { url: 'http://domain.com/openapi_1.json', // 项目名称，必须是唯一的值 projectName: 'foo', }, { url: 'http://domain.com/openapi_2.json', // 项目名称，必须是唯一的值 projectName: 'bar', }, ]);执行指令后就会生成两个类
// ./src/openapi/index.ts import { OpenapiClientFoo } from './foo'; import { OpenapiClientBar } from './bar'; export const fooClient = new OpenapiClientFoo(adapter1); export const barClient = new OpenapiClientBar(adapter2); export { OpenapiClientFoo, OpenapiClientBar };不同运行环境下，可能需要使用不同的服务端，比如开发一套服务，生产一套服务。因此执行指令时可以传入-env参数
npx openapi --env development npx openapi --env production配置文件使用回调函数的形式接收环境变量，并返回配置
import { defineConfig } from 'foca-openapi'; export default defineConfig((env) => { return { url: env === 'production' ? 'https://api.com/openapi.json' : 'http://localhost:3000/openapi.json', }; });如果不希望屏幕上有文字输出，则使用--silent参数
npx openapi --silent默认配置文件：openapi.config.ts，可以使用--config指定新的文件
npx openapi --config my-custom.config.ts类型：string
openapi本地或者远程文件，支持格式：yaml | json
类型 string
输出文件路径
- 如果没有配置项目名，默认值：
./src/openapi/openapi.ts - 如果配置了项目名，默认值：
./src/openapi/${projectName}.ts
类型：string | string[] | RegExp | RegExp[]
过滤指定路由前缀的接口
类型：string | string[]
过滤指定标签
类型：string
项目名称，提供多个openapi路径时必须填写。比如项目名为demo，则导出的类为OpenapiClientDemo
类型：'rest' | 'rpc' | 'rpc-group'
默认值：'rest'
类的生成方式。
| 模式 | 描述 | 优点 |
|---|---|---|
| rest | 仅生成统一的 get,post,put,patch,delete 几个方法 参考：rest-mode.js | 1. 运行时代码少 2. 不暴露接口，安全性高 |
| rpc | 把 method+uri 拼接成一个新方法 参考：rpc-mode.js | 1. 拥有独立的注释文档 2. 接口平铺一目了然 |
| rpc-group | 基于rpc模式，根据tags把方法归类到不同的分组中 参考：rpc-group-mode.js | 1. 拥有独立的注释文档 2. 排列类似在线文档 |
const client = new OpenapiClient(); // rest模式 await client.get('/users/{id}', opts); // rpc模式 await client.getUsersById(opts); // rpc-group模式 await client.user.getUsersById(opts);注意：rpc-group模式下，如果没有提供tags，则默认合并到default分组
类型：'method+uri' | 'operationId'
默认值：'method+uri'
指定在rpc(-group)模式下方法名的生成规则。
假设有这么一段openapi文档：
{ "paths": { "/some/client/users": { "get": { "operationId": "List_users", "parameters": [], "summary": "Users" } } } }- 如果以
method+uri的形式生成，则效果为：openapi.getSomeClientUsers() - 如果以
operationId的形式生成，则效果为：openapi.listUsers()
注意：如果operationId字段不存在，则仍以method+uri的规则生成
类型：boolean
默认值：false
开启后，query和params对象中的属性类型，number会被解析为number | string。
不管是否开启都不会对请求造成影响，因为最终都会拼接到请求链接上变成一段完整的uri。
// http://host:port/users/1?tag=234 openapi.getUsersById({ params: { id: 1 }, query: { tag: 234 } }); openapi.getUsersById({ params: { id: '1' }, query: { tag: '234' } });类型：(docs: Document) => Document | void
加载完openapi文档后的事件，允许直接对文档进行修改，或者返回新的文档