Swagger与YApi的示例分析

这篇文章将为大家详细讲解有关Swagger与YApi的示例分析，文章内容质量较高，因此小编分享给大家做个参考，希望大家阅读完这篇文章后对相关知识有一定的了解。

最近前端们一直反映Swagger看接口信息非常不爽，于是我花了俩小时把Swagger干掉，用上了传说中更好用的YApi。

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提供了几种策略，你可以选择覆盖也可以选择不覆盖。

关于Swagger与YApi的示例分析就分享到这里了，希望以上内容可以对大家有一定的帮助，可以学到更多知识。如果觉得文章不错，可以把它分享出去让更多的人看到。