Swagger UI 初体验

前言

项目组中使用了 SpringBoot + Swagger UI 来生成 Restful API 文档和测试页面。

本文来体验一下 Swagger UI 的用法。

简介

Swagger UI 是目前最流行的 RestFul 接口 API 文档和测试工具，可以直接在官方 demo 上进行体验。

本文介绍下如何在 SpringBoot2 中集成 Swagger UI。

初体验

非常简单，只需要两步即可。

依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第二个依赖中包含有前端 js/css 资源。

编写配置文件

使用
打开浏览器，访问 http://localhost:8080/swagger-ui.html 即可
api 选择器
如何只筛选出指定的 API 呢？
包名
一种方法是，根据包名来筛选
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example"))
            .paths(PathSelectors.any())
            .build();
    }

path
另一种方法是，根据 path 来筛选
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example"))
            .paths(PathSelectors.ant("/get"))
            .build();
    }

当然也可以两者配合来筛选。
详细文档
怎么样生成详细的文档呢？
通过在接口类上增加对应的注解，如下面的示例。

在类上增加 Api 注解
在方法上增加 ApiOperation 注解
在参数上增加 ApiParam 注解
在模型字段上 ApiModelProperty 增加注解

具体如下：

参考

swagger.io