1. 引入Maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2. 编写Swagger配置类
- 如果pom中还引用了spring-boot-starter-web,一定要在配置类上增加@EnableWebMvc注解。
- @EnableOpenApi是Swagger3.0的注解,默认已经开启,可选。
- 文档类型选择OAS_30,表示用swagger3.0。
- 通过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. 测试
- 我的服务配置参数是
server.port=8080
server.servlet.context-path=/accumulator
Swagger-UI的浏览器访问地址:
http://localhost:8080/accumulator/swagger-ui/index.html
最终效果