SpringBoot使用Swagger编写接口文档

一、导入坐标

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

二、编写配置类

命名自己定义

@Configuration // 配置类

@EnableSwagger2 // 开启 swagger2 的自动配置

public class SwaggerConfig{ }

具体代码如下

package com.example.demo.utils.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value(value="true")
    private Boolean swaggerEnabled;

    @Bean
    public Docket productApi() {
        // 设置请求头
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("Authorization") // 字段名
                .description("Authorization") // 描述
                .modelRef(new ModelRef("string")) // 数据类型
                .parameterType("header") // 参数类型
                .defaultValue("") // 默认值：可自己设置
                .hidden(true) // 是否隐藏
                .required(false) // 是否必须
                .build());


        return new Docket(DocumentationType.SWAGGER_2)
//                .groupName("bookstore")
                .apiInfo(apiInfo())
                .enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(parameters);

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("bookstore接口文档")
                .description("bookstore")
                .termsOfServiceUrl("www.bookstore.com")
                .version("1.0")
                .build();
    }
}

我的用于前后端分离项目，需要配置请求头信息，如果你的没有可以去掉那段配置

三、在controller层类上配置

@Api(description = "书籍列表") 用于描述类的作用
@ApiOperation("获取所有书籍列表") 用于描述类的方法的作用

运行之后是这样的, 打开地址 http://localhost:8090/swagger-ui.html#/

这里还需要注意一点的是，如果你的controller方法上使用的是@RequestMapping()的话，你的swagger界面将会是这样的。

他会默认展示所有的接口信息，包括最基础的 basic-error 相关的接口，在我那个配置已经修改好了。

所以你得使用明确的请求类型。例如@PostMapping,@GetMapping,@PutMapping,@DeleteMapping注解

@PostMapping("/selectBookListAll")，这样swagger就只会显示你写的那些接口了

四、其他注解用法

这可以标明你的每一个属性在swagger页面能看到对应的信息

@ApiModel

该注解是作用于实体类上面的，是用来描述实体类的一些基本信息的。

相关属性：

• value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
• description：对于类，提供一个详细的描述信息
• parent：这个属性用于描述的是类的一些父类信息
• discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
• subTypes：可以通过这个属性，指定我们想要使用的子类

@ApiModelProperty

该注解是用在实体类的属性上的。它的作用是添加和操作属性模块的数据。

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "Id请求体")
public class IdReq {
    @ApiModelProperty("主键id")
    private String id;
}

@ApiOperation

该注解是用在Controller类中的方法上的。用来对某个方法/接口进行描述

 @PostMapping(value = "/query-user-info")
    @ApiOperation(value = "根据id查询用户详情")
    public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) {
        return ResponseBean.success(userService.queryUserInfo(req));
    }

@ApiParam

该注解是用在Controller类的方法上或者参数上，用来进行字段说明，表示对参数的添加元数据（说明或者是否必填等）

相关属性：

• name：参数名
• value：参数说明
• required：是否必填

@PostMapping(value = "/query-user-infos")

@ApiOperation(value = "条件查询用户信息")

public ResponseBean queryUserInfos(

   // name 用户名称 不必填 @ApiParam(value = "用户名称", required = false)                 
   @RequestParam(required = false) String name,

  // gender 用户性别 必填 @ApiParam(value = "用户性别", required = true) 
  @RequestParam(required = true) GenderEnum gender ){

    return ResponseBean.success(userService.queryUserInfos(name,gender));

}