Swagger 3 的基本使用

本内容根据江南一点雨松哥的 SpringBoot 付费视频所做的学习笔记，想具体详细了解内容的，请关注微信公众号：江南一点雨。

14.1 Swagger3 准备工作

swagger2和swagger3的区别

在 SpringBoot 中使用 Swagger3 需要导入以下依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

我们导入依赖后，此时创建一个 HelloController 接口，Swagger3 会自动帮助我们生成接口文档，不需要在进行任何配置。

• 文档接口地址：http://localhost:8080/v3/api-docs
• 文档页面地址：http://localhost:8080/swagger-ui/index.html

我们访问文档页面地址可以看到项目的接口文档。

我们可以通过配置类修改接口文档UI的内容：

@Configuration
public class swaggerConfig {

    @Bean
    Docket docket(){
        // 设置 swagger的版本
        return new Docket(DocumentationType.OAS_30)
                // 选择生成接口文档
                .select()
                // 包所在的路径
                .apis(RequestHandlerSelectors.basePackage("org.crc.swagger3.controller"))
                // 当前包下所有接口都生成
                .paths(PathSelectors.any())
                .build()
                // 接口文档初始化，也就是设置接口文档的详细信息，
                .apiInfo(
                    new ApiInfoBuilder()
                        .description("xxx 项目接口文档")
                         // 联系人
                        .contact(new Contact("crc","https://blog.csdn.net/cenrc?spm=1001.2101.3001.5343","2516313840@qq.com"))
                        .version("v1.0")
                        .title("API 测试文档")
                        .license("Apache 2.0")
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                        .build()
                );
    }
}

修改之后接口文档的页面：

14.2 Swagger 3 的基本使用

注意，这里出现的注解有部分是 swagger 2中的注解，但是在swagger 3 中同样适用。

• @ApiOperation注解。

在接口中添加 @ApiOperation ，用于表述接口的作用

@ApiOperation(value = "查询用户",notes = "根据 id 查询用户")
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id){
    return "user: " + id;
}

默认情况显示：

添加注解之后显示：

@ApiOperation注解是 swagger 2 中提供的注解，swagger 3同样提供了一个类似的注解 @Operation，可以实现与 @ApiOperation注解一样的效果。

使用方式：

// swagger 2
@ApiOperation(value = "查询用户",notes = "根据 id 查询用户")
// swagger 3
@Operation(summary = "查询用户",description = "根据 id 查询用户")

• @ApiImplicitParam 注解。

基本使用方式：

@ApiImplicitParam(paramType = "path",name = "id",value = "用户 id",required = true)
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id){
    return "user: " + id;
}

@ApiImplicitParam 注解是用于描述接口的参数信息。

其中 paramType 属性表示参数的类型，参数的类型有以下几种：

path : 表示参数放在地址栏中

query ：表示参数是以 key / value 的形式传递

body ：表示参数是放在请求体中

name 属性表示参数的名字，value 属性表示参数的表述信息，required 属性表示参数是否是必须的（注意，这里相对的是swagger 接口文档而言，与项目实际运行无关）。

如果存在多个参数需要进行描述信息，那么可以使用@ApiImplicitParams注解。

@ApiImplicitParams({
        @ApiImplicitParam(paramType = "path",name = "id",value = "用户 id",required = true),
        @ApiImplicitParam(paramType = "body",name = "id",value = "用户 id",required = true)
})

默认情况显示：

添加注解之后显示：

• @ApiResponses 注解。

通过使用 @ApiResponses 注解，我们可以设置接口返回状态码的提示信息。

@ApiResponses({
        @ApiResponse(responseCode = "200",description = "请求成功"),
        @ApiResponse(responseCode = "500",description = "请求失败")
})
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id){
    return "user: " + id;
}

默认情况显示：

添加注解之后显示：

与实体类相关的注解。

• @ApiModel 注解 与 @ApiModelProperty 的结合使用。

我们通过以上两个注解用户描述实体类的相关信息。

@ApiModel(value = "用户实体类",description = "这个类定义了用户的所有属性")
public class User {
    @ApiModelProperty(value = "用户 id")
    private int id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("用户地址")
    private String address;
}

@PostMapping("/user")
public User user(@RequestBody User user){
    return user;
}

默认情况显示：

添加注解之后显示：