接口文档工具之YApi | Geepair’s Blog

type

Post

status

Published

date

Jul 22, 2024

slug

summary

旨在为开发、产品、测试人员提供更优雅的接口管理服务。

1.什么是YApi

旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API。

1.1 功能介绍

权限管理

YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求

可视化接口管理

基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率

Mock Server

易用的 Mock Server，再也不用担心 mock 数据的生成了

自动化测试

完善的接口自动化测试,保证数据的正确性

数据导入

支持导入 swagger, postman, har 数据格式，方便迁移旧项目

插件机制

强大的插件机制，满足各类业务需求

1.2 部署

环境依赖

nodejs（7.6+)

mongodb（2.6+）

可视化部署


npm install -g yapi-cli --registry https://registry.npm.taobao.org
yapi server

命令行部署


mkdir yapi
cd yapi
git clone https://github.com/YMFE/yapi.git //或者下载 zip 包解压到 vendors 目录（
cd yapi
cp config_example.json config.json //复制完成后请修改相关配置
npm install --production //安装程序会初始化数据库索引和管理员账号，管理员账号名可在 config.json 配置
node server/app.js //启动服务器后，请访问 127.0.0.1:{config.json配置的端口}，初次运行会有个编译的过程，请耐心等候

1.3 开放Api

项目操作

项目操作

菜单操作

接口列表操作

新增接口分类
获取某个分类接口列表
…

接口操作

新增/更新接口
获取接口
…

1.4 页面使用

权限

项目操作

基本设置
新建项目
修改项目
项目迁移
项目拷贝
配置环境
请求配置
token配置
全局mock
…

接口操作

接口设置
接口运行
…

数据mock

mockjs
json-schema

高级mock

mock期望
自定义脚本

自动化测试

数据导入

2.EasyYApi

For yapi Not only for yapi

2.1 核心功能

多语言

Java/Kotlin/Scala

多框架

Spring/Feign/Jaxrs(Quarkus or Jersey)

多渠道

Postman/Markdown/Yapi

丰富的扩展性

支持多种配置与扩展,满足不同框架与代码规范

调试利器

一个小巧的内置类postman工具

2.2 介绍

基于javadoc&KDoc&ScalaDoc解析API文档

可以在保持代码零侵入的情况下得到相当完整的api文档, 但是特殊的需求还是需要部分特殊的注释/注解配合

可以灵活的运用配置规则来适应你的项目特性以减少代码侵入

功能特性

导出API文档（yapi/postman/markdown）

在IDEA中直接发起API请求

支持列表

ㅤ	默认支持	额外(配置)支持
语言	java, kotlin	scala
web	spring, feign, jaxrs (quarkus / jersey)	dubbo
导出到	Postman, Yapi, Markdown	ㅤ
常用框架	javax.validation, Jackson, Gson	swagger

2.3 安装

Jetbrains插件商城

EasyYapi - IntelliJ IDEs Plugin | Marketplace

easy-yapi GitHub | Issues | Guide Help you export API to yapi/postman/markdown Parse API documents based on javadoc & KDoc & ScalaDoc Note: It's possible to...

https://plugins.jetbrains.com/plugin/12458-easyyapi

2.4 配置规则

使用IDEA全局配置

image.png - SM.MS - Simple Free Image Hosting

Simple Free Image Hosting

https://sm.ms/image/QMbL2GzKgxiv9YE

image.png - SM.MS - Simple Free Image Hosting

使用项目内配置文件（推荐properties）

文件	类型	适用的操作
.easy.api.config	properties	markdown/postman/yapi/call
.easy.api.yml/.easy.api.yaml	yml	markdown/postman/yapi/call
.postman.config	properties	postman
.postman.yml/.postman.yaml	yml	postman
.yapi.config	properties	yapi
.yapi.yml/.yapi.yaml	yml	yapi


#单行配置
http.call.before=groovy:logger.info("call:"+request.url())
#以\接新行
http.call.before=groovy:\
logger.info("call:"+request.url())
#以```包裹多行
http.call.before=groovy:```
logger.info("call:"+request.url())
```

使用远程配置文件


properties.additional=https://raw.githubusercontent.com/tangcent/easy-yapi/master/third/swagger.config

yapi 相关配置

服务地址

token

postman相关配置

token

可用规则配置

.recommend.easy.api.config

tangcent

支持的规则支持的简单配置支持的回调规则语法-配置

Simplifies API Development

https://easyyapi.com/setting/config-rule.html

规则的key	规则目标(上下文it)	版本	规则描述
api.name	method	v1.4.1+	设置api的名称
api.tag	method	v0.7.5+	标记接口tag
api.open	method	v1.9.4+	标记接口是否公开
api.status	method	v0.8.0+	标记接口status(应返回done/undone)
class.doc	class	v1.3.0+	类上的额外注释
class.is.ctrl	method	v2.0.8+	允许导出指定类中的`api`
class.postman.prerequest	class	v1.9.5+	设置`postman·folder`上的`prerequest`
class.postman.test	class	v1.9.5+	设置`postman·folder`上的`test`
class.prefix.path	class	v1.3.0+	设置API请求前缀
collection.postman.prerequest	class	v1.9.5+	设置`postman·collection`上的`prerequest`
collection.postman.test	class	v1.9.5+	设置`postman·collection`上的`test`
constant.field.ignore	field	v1.3.8+	忽略常量字段
enum.use.custom	class	v2.4.1+	用于设置使用`@see`枚举类型时的默认取值字段, 优先级高于enum.use.by.type
enum.use.by.type	class	v2.4.1+	用于设置使用`@see`枚举类型时的默认使用类型一致的字段, 优先级低于enum.use.custom
enum.use.ordinal	class	v2.2.1+	用于设置使用`@see`枚举类型时的默认使用`ordinal`作为取值
enum.use.name	class	v2.2.1+	用于设置使用`@see`枚举类型时的默认使用`name`作为取值
field.advanced	field	v2.2.8+	提供`yapi`的高级设置信息
field.default.value	-	v1.7.1+	用以设置字段的默认值
field.demo	-	v1.9.3+	用以设置字段的示例值
☆field.doc	field	v0.7.2+	字段的额外注释
field.ignore	field	v2.0.0+	忽略字段(设置某些字段不出现在json中,或不需要请求时给出)
☆field.mock	field	v1.4.2+	生成`yapi`mock信息
field.mock.resolveProperty	-	v1.4.2+	用以开关是否解析`field.mock`规则结果中的占位符
field.name	field	v0.7.2+	设置输出的字段名(用于json中字段名与类中字段名不一致)
field.required	field	v0.7.3+	字段是否为必须(即不可为空)
field.order	field	v2.6.4+	用于指定字段顺序
field.order.with	field	v2.6.4+	用于设置字段顺序
field.type	field	v2.6.4+	用于设置字段实际数据类型
folder.name	method	v1.9.2+	设置api所属文件夹
ignore	class/method	v0.7.2+	忽略API
☆json.rule.convert	-	v0.7.2+	用于设置某些类型转换为其他类型处理, 通常用于使用了Spring的自定义类型转换器的情况
json.rule.enum.convert	class	v1.2.0+	用于枚举类型的特殊转换
~~json.rule.field.ignore~~	field	v0.7.2+	忽略字段(设置某些字段不出现在json中,或不需要请求时给出) 已废弃, 使用field.ignore代替
~~json.rule.field.name~~	field	v0.7.2+	设置输出的字段名(用于json中字段名与类中字段名不一致)
mdoc.class.filter	class	v0.9.5+	选择哪些类可以导出方法文档(rpc)
mdoc.method.filter	method	v0.9.5+	选择哪些方法可以导出方法文档(rpc)
mdoc.method.path	method	v0.9.5+	设置方法文档(rpc)的路径
mdoc.method.http.method	method	v0.9.5+	设置方法文档(rpc)HTTP请求方式
method.additional.header	method	v1.3.0+	API需要额外的header
ㅤ	ㅤ	ㅤ	{name: "header name",value: "",desc: "",required:false, example:""}
method.additional.param	method	v1.3.0+	API需要额外的参数
ㅤ	ㅤ	ㅤ	{name: "param name",value: "defaultValue",desc: "",required:false}
method.additional.response.header	method	v1.3.0+	API的响应包含额外的header
ㅤ	ㅤ	ㅤ	{name: "header name",value: "",desc: "",required:false, example:""}
method.content.type	-	v1.9.7+	用以设置API请求的content-type
method.default.http.method	method	v1.4.2+	设置默认的api的HttpMethod
method.doc	method	v0.7.2+	方法(api)的额外注释
☆method.return.main	method	v1.3.8+	设置返回值的核心主体
☆method.return	method	v1.6.1+	设置返回值的类型
module	class	v0.7.2+	为api分组
param.default.value	arg	v1.3.0+	API参数的默认值
param.demo	-	v1.9.3+	用以设置参数的示例值
param.doc	arg	v1.3.0+	参数的额外注释
param.http.type	arg	v2.0.0+	用于设置API参数在HTTP请求中的类型
param.ignore	arg	v1.3.0+	忽略API参数
param.required	arg	v0.7.3+	API参数是否为必须(即不可为空)
path.multi	method	v1.9.2+	当API有多个路径时如何选择
postman.host	class	v1.5.2+	设置`postman`API的host
postman.prerequest	class	v1.9.5+	设置`postman`API的`prerequest`
postman.test	class	v1.9.5+	设置`postman`API的`test`

支持回调

脚本工具

工具/对象	规则描述
☆it	当前规则的应用对象(大多数规则可用)
☆tool	主工具类
regex	正则工具
logger	日志工具
helper	特殊帮助类
httpClient	http相关帮助类
localStorage	本地存储
session	临时存储
config	配置读取工具
runtime	运行时信息
fieldContext	字段上下文类