Swagger与YApi的示例分析
这篇文章将为大家详细讲解有关Swagger与YApi的示例分析,文章内容质量较高,因此小编分享给大家做个参考,希望大家阅读完这篇文章后对相关知识有一定的了解。
创新互联长期为近1000家客户提供的网站建设服务,团队从业经验10年,关注不同地域、不同群体,并针对不同对象提供差异化的产品和服务;打造开放共赢平台,与合作伙伴共同营造健康的互联网生态环境。为江川企业提供专业的成都网站设计、成都网站建设,江川网站改版等技术服务。拥有10多年丰富建站经验和众多成功案例,为您定制开发。
最近前端们一直反映Swagger看接口信息非常不爽,于是我花了俩小时把Swagger干掉,用上了传说中更好用的YApi。
Swagger与YApi
其实我个人认为Swagger也没啥不好的,后端集成起来方便快捷,就是UI不行,而且对于Java来说代码的侵入性太高了。
swagger界面
YApi除了解决了这些问题之外还具有权限管理、团队协作、自动化测试、支持OpenApi规范等等。
YApi界面
YApi区别于Swagger的最大不同就是YApi需要导入文档(虽然它也可以通过Swagger轮询导入),而Swagger可以自动发现。
安装这里就不细说了,官方文档说的很清楚。你可以选择命令行部署、可视化部署,也能使用Docker部署。
推荐内网部署,毕竟大部分API文档比较敏感。
文档注释
YApi的文档解析基于Java注释规范,没有代码侵入!但是这就要求我们要按照Javadoc的规范进行书写文档注释,这是使用YApi的前提。一个接口文档分为以下几个部分。
接口类注释
接口类的注释,下面是基本的格式。第一行会作为菜单展示,尽量短小精悍;第二行是接口的描述,用来描述接口的作用和细节。
/** * 接口分类名称 ** 接口备注/描述 * * @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提供了几种策略,你可以选择覆盖也可以选择不覆盖。
关于Swagger与YApi的示例分析就分享到这里了,希望以上内容可以对大家有一定的帮助,可以学到更多知识。如果觉得文章不错,可以把它分享出去让更多的人看到。
新闻标题:Swagger与YApi的示例分析
当前路径:http://scyanting.com/article/gpjgjp.html