SpringBoot 集成 Swagger 构建Restful

Swagger 是一个简单但功能强大的 API 表达工具。它具有地球上最大的 API 工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用 Swagger。使用 Swagger 生成 API，我们可以得到交互式文档，自动生成代码的 SDK 以及 API 的发现特性等。

使用 Spring Boot 集成 Swagger 的理念是，使用注解来标记出需要在 API 文档中展示的信息，Swagger 会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具，它提供了 API 管理的全套解决方案，API 文档管理需要考虑的因素基本都包含，这里将讲解最常用的定制内容。

环境以及版本：

SpringBoot ： 2.0.5.RELEASE
JDK ：1.8

maven 依赖

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

创建 SwaggerConfig 配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

然后添加
在 SwaggerConfig 的类上添加两个注解：

@Configuration，启动时加载此类
@EnableSwagger2，表示此项目启用 Swagger API 文档
在 SwaggerConfig 中添加两个方法：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // 自行修改为自己的包路径
            .apis(RequestHandlerSelectors.basePackage("com.neo.xxx"))
            .paths(PathSelectors.any())
            .build();
}

主要配置页面展示的基本信息包括，标题、描述、版本、服务条款、联系方式等，查看 ApiInfo 类的源码还会发现支持 license 配置等。

启动后

在这里插入图片描述

访问地址可以看到

在这里插入图片描述

还可以进行测试

在这里插入图片描述

结果

在这里插入图片描述

Swagger 常用注解

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息等，常用注解内容如下：

作用范围 API 使用位置
协议集描述 @Api 用于 Controller 类上
协议描述 @ApiOperation 用在 Controller 的方法上
非对象参数集 @ApiImplicitParams 用在 Controller 的方法上
非对象参数描述 @ApiImplicitParam 用在 @ApiImplicitParams 的方法里边
响应集 @ApiResponses 用在 Controller 的方法上
响应信息参数 @ApiResponse 用在 @ApiResponses 里边
描述返回对象的意义 @ApiModel 用在返回对象类上
对象属性 @ApiModelProperty 用在出入参数对象的字段上

@Api 的使用
Api 作用在 Controller 类上，做为 Swagger 文档资源，该注解将一个 Controller（Class）标注为一个 Swagger 资源（API）。在默认情况下，Swagger-Core 只会扫描解析具有 @Api 注解的类，而会自动忽略其他类别资源（JAX-RS endpoints、Servlets 等）的注解。

@Api(value = "验证测试",description = "验证数据",consumes = "application/json",produces = "http",hidden = true)
@RestController
public class validController {

与 Controller 注解并列使用，属性配置如表所示：

属性名称 备注
value url 的路径值
tags 如果设置这个值，value 的值会被覆盖
description 对 API 资源的描述
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss
authorizations 高级特性认证时配置
hidden 配置为 true 将在文档中隐藏

在这里插入图片描述

@ApiOperation 的使用
ApiOperation 定义在方法上，描述方法名、方法解释、返回信息、标记等信息。

  @ApiOperation(
            value = "save 消息列表",
            notes = "save 完整的消息内容列表",
            produces="application/www-xxxxx, application/xml",
            consumes="application/json, application/xml",
            response = List.class
    )

属性名称 备注
value url 的路径值
tags 如果设置这个值、value的 值会被覆盖
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss
authorizations 高级特性认证时配置
hidden 配置为 true 将在文档中隐藏
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map"，其他无效
httpMethod "GET"、"HEAD"、"POST"、"PUT"、"DELETE"、"OPTIONS" and "PATCH"
code http 的状态码 默认 200
extensions 扩展属性

在这里插入图片描述

@ApiImplicitParams 和 @ApiImplicitParam 的使用
@ApiImplicitParams 用于描述方法的返回信息，和 @ApiImplicitParam 注解配合使用；@ApiImplicitParam 用来描述具体某一个参数的信息，包括参数的名称、类型、限制等信息。

   @ApiOperation(
            value = "save 消息列表",
            notes = "save 完整的消息内容列表",
            produces="application/www-xxxxx, application/xml",
            consumes="application/json, application/xml",
            response = List.class
    )
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "消息 ID", required = true, dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "int", paramType = "query"),
    })

属性名称 备注
name 接收参数名
value 接收参数的意义描述
required 参数是否必填值为 true 或者 false
dataType 参数的数据类型只作为标志说明，并没有实际验证
paramType 查询参数类型，其值：
path 以地址的形式提交数据
query 直接跟参数完成自动映射赋
body 以流的形式提交，仅支持 POST
header 参数在 request headers 里边提交
form 以 form 表单的形式提交 仅支持 POST
defaultValue 默认值

在这里插入图片描述

@ApiResponses 和 @ApiResponse 的使用
@ApiResponses 主要封装方法的返回信息和 @ApiResponse 配置起来使用，@ApiResponse 定义返回的具体信息包括返回码、返回信息等。

  @ApiOperation(value = "修改用户", notes = "根据参数修改用户")
    @ApiResponses({
            @ApiResponse(code = 100, message = "请求参数有误"),
            @ApiResponse(code = 101, message = "未授权"),
            @ApiResponse(code = 103, message = "禁止访问"),
            @ApiResponse(code = 104, message = "请求路径不存在"),
            @ApiResponse(code = 200, message = "服务器内部错误")
    })
    @PutMapping(value = "updateUser")
    public ReturnModle updateUser(@Valid User user, BindingResult result) {
      return null;
    }

属性名称 备注
code http 的状态码
message 描述
response 默认响应类 Void
reference 参考
responseHeaders 封装返回信息
responseContainer 字符串

在这里插入图片描述

@ApiModel 和 @ApiModelProperty 的使用
在实际的项目中我们常常会封装一个对象作为返回值，@ApiModel 就是负责描述对象的信息，@ApiModelProperty 负责描述对象中属性的相关内容。

  @ApiOperation(value = "修改用户", notes = "根据参数修改用户")
    @PatchMapping(value = "updateUser")
    public ReturnModle<User> updateUser(@Valid User user, BindingResult result) {
      return new ReturnModle(0,"成功",user);
    }

在这里插入图片描述

总结

通过 "丝袜哥"我们可以构建一个很强大的restful api 文档

我们既可以在管理界面测试也可以看到相应的数据，也可以通过命令方式去测试。

测试

在这里插入图片描述

点击 try it out 进行测试

在这里插入图片描述
响应
在这里插入图片描述