api-refs v1.1.5
这是一个能够显著提高前端接口管理效率的工具。基于 apifox 的 JSONSchema 规范, 生成前端项目使用的接口调用文件.
About
- 🚀 效率提升 自动化完成前端接口对接工作, 减少接口对接的工作量.
- 🍼 类型提示 生成结果完美还原接口文档类型, 能够显著降低开发阶段代码拼写错误的产生.
- 📖 配置简单 配置文件提供了
JSONSchema
支持, 能够及时检测配置错误、或工具更新产生的配置差异. - ✈ 及时性 可观测接口文档变化, 结合 git 工具, 可在每次生成后, 实时反馈接口文档的变化.
- 📌一致性 通过一致的代码结构, 减少不同代码风格产生的差异, 有利于大体量项目场景的长期维护.
其他
- module support:
cjs
、esm
- 更完善地参数类型支持:
params
,data
,header
,cookie
,auth
- module support:
文档管理工具支持 (逐步更新)
- apifox ✔
- apipost []
- swagger []
Usage
- 安装
yarn add api-refs --dev
# or
npm install api-refs
- 增加快捷命令 (package.json)
Tips: 可根据需要指定其他命令名
{
"scripts": {
"api:ref": "api-refs"
},
}
- 生成 (首次生成时, 需要遵循提示进行简单配置)
yarn api:ref
- 其他一些命令参数
# 一般生成, 首次生成需配置
yarn api:ref
# 查看帮助
yarn api:ref -h
# 重新生成配置文件
yarn api:ref -r
# 指定配置文件 (当同一项目使用多个文档内接口可能会用到, 但不建议这么使用)
yarn api:ref -c < config file path >
# 覆盖配置信息
yarn api:ref -s < key > < value >
# 生成请求工具文件 (request.ts)
yarn api:ref ir
Config
TIPS 为了照顾大多数的使用场景的使用体验, 小部分兼容性配置需要手工设置, 具体可参考接口参数
FAQ
1. 如何指定自定义请求工具 ?
默认情况下, 建议使用 axios
, 并将实例放置到 @/utils/request
文件内. 如果你的项目不满足上述条件, 可以通过以下方式自定义请求工具.
首先, 自定义请求工具需要继承
axios
实例, 或具备与axios
相同的 api.修改生成配置
api-refs.config.json
, 通过output.applyImportStatements
字段指定请求工具路径重新生成
2. 接口文档交付问题
一般做存档使用时, 建议统一管理apifox
即可, 但如果需要文档形式的接口文档时, 可使用 apifox 进行文档导出, 还是比较便捷和规范的.
3. 关于生成策略
原定的计划是准备生成 ast 语法树, 然后在转化成代码的, 实验了一下, 发现这样做会使生成逻辑增大 2 倍, 所以还是改回了原来的基于文本拼接方式生成. 当然了, 这种方式虽然在代码量以及性能上面略有优势, 但可能会牺牲一定的稳定性, 所以如果生成失败的情况下, 请尝试调整接口文档的设计, 并重新生成即可.
7 months ago
9 months ago
7 months ago
9 months ago
9 months ago
9 months ago
8 months ago
6 months ago
8 months ago
6 months ago
8 months ago
7 months ago
9 months ago
10 months ago
7 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
12 months ago