树栢de博客
一、添加MAVEN依赖
<!-- 版本号 -->
<swagger2.version>3.0.0</swagger2.version>
<knife4j-spring-boot-starter.version>3.0</knife4j-spring-boot-starter.version>
<!-- swagger2 begin-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>${swagger2.version}</version>
</dependency>
<!-- 使用了bootstrap版本的swagger ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j-spring-boot-starter.version}</version>
</dependency>
<!-- swagger2 end-->
二、添加Swagger2Config配置文件
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Value("${version}")
private String version;
// 如果需要分组可以配置多个，如果不需要分组只创建一个默认Bean就可以了，groupName前面的0，1是为了排序
@Bean
public Docket createDefaultRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(true)
// 指定分组
.groupName("0-全部接口")
// 描述信息
.apiInfo(apiInfo("SERVER 服务", "提供前端所需所有接口"))
.select()
// 需要扫描的包路径
.apis(RequestHandlerSelectors.basePackage("com.XXX.server.controller"))
.paths(PathSelectors.any())
.build();
}
public ApiInfo apiInfo(String title, String description) {
return new ApiInfoBuilder()
.title(title)
.description(description)
.contact(new Contact("IT中心", null, null))
.version(version)
.build();
}
}
三、添加ServerConfig配置类 (如果有，在之前的配置文件中新增即可)
@Configuration
public class ServerConfiguration implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**")
.addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
四、在application.yml文件中添加版本配置
version: @project.version@
五、如果项目中有请求拦截器，需要忽略拦截
- /swagger-resources/**
- /v2/api-docs
六、如果项目中有返回值拦截器，返回值忽略拦截
- springfox.documentation.swagger.*
- springfox.documentation.swagger2.*
七、在接口上添加注解(不添加的话也能扫描到，只是没有中文解释)
- 在类上添加 @Api(tags = “描述类的作用”)
- 在方法上添加 @ApiOperation(“描述方法的作用”)
- 参数描述有多种方式
- 描述单个参数可以在参数上用 @ApiParam(value=”参数描述”, requried = true)
- 描述单个参数可以在方法上用 @ApiImplicitParam(name=”code” , value=”参数描述”, requried = true)
- 统一描述多个参数可以在方法上用 @ApiImplicitParams({ @ApiImplicitParam(name=”code” , value=”编号”, requried = true), @ApiImplicitParam(name=”name” , value=”姓名”, requried = true) })
- 如果参数是实体类，在类上添加 @ApiModel ，然后在每个字段上添加 @ApiModelProperty(value = “字段描述”, example = “示例值”)
- 定义错误码
- 描述单个错误码，在方法上用 @ApiResponse(responseCode = “360102”, description = “菜单编号不存在”)
- 描述多个错误码，在方法上用 @ApiResponses({ @ApiResponse(responseCode = “360102”, description = “菜单编号不存在”), @ApiResponse(responseCode = “360102”, description = “菜单编号不存在”) })