1. 引入Maven依赖

springfox GitHub

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

2. 编写Swagger配置类

1. 如果pom中还引用了spring-boot-starter-web，一定要在配置类上增加@EnableWebMvc注解。
2. @EnableOpenApi是Swagger3.0的注解，默认已经开启，可选。
3. 文档类型选择OAS_30，表示用swagger3.0。
4. 通过enable参数配置来控制swagger的开关，在生产环境中，swagger功能不需要开启。

import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi // 可选
@EnableWebMvc // spring-boot-starter-web冲突会引发启动服务时null，必选
public class SwaggerConfig {

    @Value("${swagger.enable:true}")
    private boolean enable;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // 3.0要选择OAS_30
                .apiInfo(apiInfo())
                .enable(enable)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                 // 正则表达式来拦截swagger要输出的接口
                 // .paths(PathSelectors.regex(".*crud.*")) 
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Accumulator接口文档")
                .version("1.0")
                .build();
    }
}

3. 编写处理器类Controller

Swagger的注解常用的有@Api，@ApiOperation，@ApiParam， @ApiImplicitParams, @ApilmplicitParam，@ApiModel，@ApiModelProperty，具体用法请参考这篇文章

@Api(tags = "人员相关接口")
@Slf4j
@RestController
@RequestMapping("/person")
public class PersonController {

    @Resource
    private ExcelComponent excelComponent;

    @Resource
    private PersonMapper personMapper;

    @ApiOperation("新增人员")
    @LogAnnotation(type = EnumLogType.INSERT, operateLog = "新增人员")
    @PostMapping("/add")
    public ResponseResult<Boolean> addPerson(@RequestBody PersonParam param) {
        param.setId(null);
        PersonPO personPO = new PersonPO();
        BeanUtils.copyProperties(param, personPO);
        personMapper.insert(personPO);
        ResponseResult<Boolean> result = ResponseResult.success(true);
        result.setBusinessLog("人员ID:" + personPO.getId());
        return result;
    }

    @ApiOperation("修改人员")
    @LogAnnotation(type = EnumLogType.UPDATE, operateLog = "修改人员")
    @PostMapping("/modify")
    public ResponseResult<Boolean> modifyPerson(@RequestBody PersonParam param) {
        Assert.isTrue(param.getId() != null, "修改人员的ID不能为空");
        PersonPO personPO = new PersonPO();
        BeanUtils.copyProperties(param, personPO);
        personMapper.updateById(personPO);
        ResponseResult<Boolean> result = ResponseResult.success(true);
        result.setBusinessLog("人员ID:" + param.getId());
        return result;
    }

    @ApiOperation("删除人员")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id", value = "人员ID", required = true)
    })
    @LogAnnotation(type = EnumLogType.DELETE, operateLog = "删除人员,ID:{#id}", containsParam = true)
    @PostMapping("/delete/{id}")
    public ResponseResult<Boolean> deletePerson(@PathVariable Long id) {
        personMapper.deleteById(id);
        return ResponseResult.success(true);
    }
}

4. 测试

1. 我的服务配置参数是

server.port=8080
server.servlet.context-path=/accumulator

Swagger-UI的浏览器访问地址：
http://localhost:8080/accumulator/swagger-ui/index.html
最终效果

swagger-ui