背景
当我们使用Spring编写接口后,需要接口文档化,方便测试与前端人员使用该接口。此处我们使用了Yapi作为API文档工具而不是Swagger,这是技术选择导致的。
为了方便我们将spring的Controller导出到Yapi,有款idea的插件非常方便有效。
安装说明
安装EasyApi插件
在idea设置中配置好yapi服务器地址和个人的tokens
token获取
使用说明
以下面的代码为例
/**
* 这部分会变成分组名
* 这部分是分组的说明信息
*
* @Description 活动
* @Author ZhouLiangCheng
* @Date 2022/10/20
* @Version 1.0
*/
@RestController
@RequestMapping("/export/yapi")
public class ExportYapiController {
/**
* 这部分会作为api的名称
* 这部分会变成api的说明信息
*
* @param param1 参数1的描述
* @param param2 {@link DescEnum#bb}
* @param param3 {@link DescEnum#aa}
* @return desc of response
*/
@GetMapping("/get1")
public Result<String> get1(Long param1, @RequestParam String param2,
@RequestParam(required = false, defaultValue = "aa") DescEnum param3) {
return Result.success("123");
}
/**
* 废弃请求
* 默认请求类型为 content-type:`application/x-www-form-urlencoded`,
* 但是标记有 @RequestBody 的参数会设置为 'application/json'
*
* @param map 任意
* @return version
* @deprecated use {@link #post2(Map)} )} instead of
*/
@Deprecated
@PostMapping("/post1")
public Result<Integer> post1(@RequestBody Map<String, String> map) {
return Result.success(1);
}
/**
* 船新版本
*
* @param map 任意
* @return version
*/
@PostMapping("/post2")
public Result<Integer> post2(@RequestBody Map<String, String> map) {
return Result.success(2);
}
@Getter
@AllArgsConstructor
public static enum DescEnum {
// desc
aa("this a"),
bb("from b"),
;
final String desc;
}
}
完整的操作演示(视屏暂时被吞了)
EasyApi演示
使用EasyApi导出到Yapi后的效果
分组信息
正常接口信息
扫描二维码关注公众号,回复:
16325986 查看本文章
废弃接口信息
总结
EasyApi 这插件不仅支持导出到Yapi,还支持Postman,MarkDown等多种方式,而非其名字表示的那样简单。
如果大家用着方便,请git上点个start。