抱怨Swagger不好用？好吧我换一个好用的
Swagger与YApi
其实我个人认为Swagger也没啥不好的，后端集成起来方便快捷，就是UI不行，而且对于Java来说代码的侵入性太高了。
swagger界面
YApi除了解决了这些问题之外还具有权限管理、团队协作、自动化测试、支持OpenApi规范等等。
YApi界面
YApi区别于Swagger的最大不同就是YApi需要导入文档(虽然它也可以通过Swagger轮询导入)，而Swagger可以自动发现。
安装这里就不细说了，官方文档说的很清楚。你可以选择命令行部署、可视化部署，也能使用Docker部署。
❝推荐内网部署，毕竟大部分API文档比较敏感。
文档注释
YApi的文档解析基于Java注释规范，没有代码侵入！但是这就要求我们要按照Javadoc的规范进行书写文档注释，这是使用YApi的前提。一个接口文档分为以下几个部分。
接口类注释
接口类的注释，下面是基本的格式。第一行会作为菜单展示，尽量短小精悍；第二行是接口的描述，用来描述接口的作用和细节。
/**
* 接口分类名称
* <p>
* 接口备注/描述
*
* @author felord
* @since v1.0
*/
@RestController
@RequestMapping("/foo")
public class FooController {
// 省略
}
接口类对应的文档
❝还有
@module、@copyright什么的其实可以不写。
参数注释
入参和出参的注释，配合JSR-303有奇效哦。
/**
* 账户基本信息
*
* @author felord
* @since v1.0
*/
@Data
public class UserInfoDetail {
/**
* 用户名
*
* 配合JSR303注解声明此字段的约束方式【必填】
*/
@NotBlank
private String username;
/**
* 真实姓名
*/
private String realName;
/**
* 手机号码
*/
private String phoneNumber;
/**
* 性别 -1 未知 0 女性 1 男性
*
* 使用@see来说明该字段的取值来源
* @see GenderType#value()
*/
private Integer gender;
/**
* 昵称
*/
private String nickName;
/**
* 微信号
* 使用{@code Deprecated} 表示字典将来会废弃
*/
@Deprecated
private String wechatAccount;
/**
* 电子信箱
*/
private String email;
}
接口方法注释
入参为复杂对象的话注释用@link引用，@RequestBody会指定Content-Type为application/json。
/**
* 新增用户信息
*
* @param userInfoDetail 用户信息参数 {@link UserInfoDetail}
* @return {@link Boolean}
*/
@PostMapping("/bar")
public boolean detail(@RequestBody UserInfoDetail userInfoDetail) {
return true;
}
Post请求对应的样式
如果参数是原始类型类型或者String,可以这样写，@RequestParam有奇效。
/**
* 获取用户信息
*
* @param name 姓名
* @param age 年龄
* @return {@link UserInfoDetail}
*/
@GetMapping("/sam")
public UserInfoDetail detailBySamples(@RequestParam String name, Integer age) {
return new UserInfoDetail();
}
Get请求对应的样式
导入文档
YApi支持Swagger、Postman、JSON等方式导入文档。不过我个人更喜欢使用插件导入，Intellij IDEA中推荐使用easy-yapi。导入的时候定位到对应的Controller,使用快捷键Alt+Ins呼出快捷菜单。
呼出快捷菜单
选择Export Yapi ，首次选择会让你输入YApi的服务器地址，还会让你输入对应项目的token字符串。
token 字符串
依次填入后，就会解析生成文档并同步到YApi服务器了，结果就是上面截图中的样子。然后你可以配置权限分配给组员使用了，如果有文档更新重复上面的步骤即可，YApi提供了几种策略，你可以选择覆盖也可以选择不覆盖。YApi提供了比Swagger更丰富的功能，具体我还在探索中，如果有什么好玩的，会在后面分享给大家，还请多多关注。
腾讯云开发者
