foca-openapi
v1.3.0
Published
根据openapi文档生成请求客户端
Downloads
1,277
Readme
foca-openapi
使用openapi文档生成请求服务。支持 Openapi 3.0
安装
pnpm add foca-openapi
使用
1. 创建配置文件
在项目根目录下创建一个名为 openapi.config.ts
的文件
import { defineConfig } from 'foca-openapi';
export default defineConfig({
// 可以是本地路径,也可以是远程地址
url: 'http://domain.com/openapi.json',
});
2. 执行指令
指令的作用是把openapi文档转换为前端服务,代码会自动合并到库文件中
npx openapi
3. 创建服务
使用合适的请求适配器创建好服务后,就可以导出给各个模块使用了
// ./src/services/http.ts
import { OpenapiClient } from 'foca-openapi';
import { fetchAdapter } from 'foca-openapi/adapters/fetch';
const adapter = fetchAdapter({ baseURL: 'http://api.com' });
export const client = new OpenapiClient(adapter);
适配器
引入形式
import { xxAdapter } from 'foca-openapi/adapters/xx';
当前已内置多个适配器,可满足大部分需求。如果无法满足项目需求则可以自行创建适配器(或者提issue)
- axios
- fetch
- taro
- uniapp
多配置场景
如果一个项目需要融合多个openapi文档,则可以用数组的形式配置
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',
},
]);
执行指令后就会生成两个类
import { OpenapiClientFoo, OpenapiClientBar } from 'foca-openapi';
export const fooClient = new OpenapiClientFoo(adapter1);
export const barClient = new OpenapiClientBar(adapter2);
CLI选项
环境变量
不同运行环境下,可能需要使用不同的服务端,比如开发一套服务,生产一套服务。因此执行指令时可以传入-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
参数
url
类型:string
openapi本地或者远程文件,支持格式:yaml | json
includeUriPrefix
类型:string | string[] | RegExp | RegExp[]
过滤指定路由前缀的接口
includeTag
类型:string | string[]
过滤指定标签
projectName
类型:string
项目名称,提供多个openapi路径时必须填写。比如项目名为demo
,则导出的类为OpenapiClientDemo
classMode
类型:'rest' | 'rpc' | 'rpc-group'
默认值:'rest'
类的生成方式。
| 模式 | 描述 | 优点 | | --------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | rest | 仅生成统一的 get,post,put,patch,delete 几个方法参考:rest-mode.js | 1. 运行时代码少2. 不暴露接口,安全性高 | | rpc | 把 method+uri 拼接成一个新方法参考:rpc-mode.js | 1. 拥有独立的注释文档 | | 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
分组
onDocumentLoaded
类型:(docs: Document) => Document | void
加载完openapi文档后的事件,允许直接对文档进行修改