抱怨Swagger不好用?好吧我换一个好用的

Posted Hollis Chuang

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了抱怨Swagger不好用?好吧我换一个好用的相关的知识,希望对你有一定的参考价值。

最近前端们一直反映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-Typeapplication/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支持SwaggerPostmanJSON等方式导入文档。不过我个人更喜欢使用插件导入,Intellij IDEA中推荐使用easy-yapi。导入的时候定位到对应的Controller,使用快捷键Alt+Ins呼出快捷菜单。

呼出快捷菜单

选择Export Yapi ,首次选择会让你输入YApi的服务器地址,还会让你输入对应项目的token字符串。

token 字符串

依次填入后,就会解析生成文档并同步到YApi服务器了,结果就是上面截图中的样子。然后你可以配置权限分配给组员使用了,如果有文档更新重复上面的步骤即可,YApi提供了几种策略,你可以选择覆盖也可以选择不覆盖。YApi提供了比Swagger更丰富的功能,具体我还在探索中,如果有什么好玩的,会在后面分享给大家,还请多多关注。

有道无术,术可成;有术无道,止于术

欢迎大家关注Java之道公众号

好文章,我在看❤️

以上是关于抱怨Swagger不好用?好吧我换一个好用的的主要内容,如果未能解决你的问题,请参考以下文章

抱怨GitHub

这个火爆技术圈的神器,全面超越Postman和Swagger!

好吧,我承认我是HTML里的小白。怎么在HTML里将搜索框做成这个样子。。

再见 Swagger UI!国人开源了一款超好用的 API 文档生成框架,Star 4.7K+,真香!!

开启服务器固件测试之路

Swagger UI教程 API 文档神器 搭配Node使用