Springboot2x集成Swagger2
一、环境
- jdk 1.8
- Swagger 2.9.2
- Swagger-ui 2.9.2
- Spring Boot 2.1.9
二、代码示例
//导入依赖：
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
//添加如下配置类：
@Configuration
@EnableSwagger2
@EnableAutoConfiguration
public class Swagger2Config {
/**
*
* @return
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//此处根据情况自行添加需要将哪些接口纳入Swagger 文档管理。此处应用basePackage管理，还可以利用注解管理
//如果填写错误的话会出现“No operations defined in spec!” 的问题。
.apis(RequestHandlerSelectors.basePackage("com.iammn.controller"))
.paths(PathSelectors.any())
.build();
}
/**
*
* @return
*/
private ApiInfo apiInfo(){
Contact contact = new Contact("Swagger2 demo", "http://localhost", "邮箱");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTFUL API")
.description("描述信息")
.termsOfServiceUrl("http://localhost")
.version("1.0")
.contact(contact)
.build();
}
}
//示例controller 类:
@RestController
@Api(value = "测试 swagger2")
public class Swagger2TestController {
/**
*
* @param param
* @return
*/
@RequestMapping(value = "/swagger", method = RequestMethod.GET)
@ApiOperation(value = "返回用户输入的参数内容", notes = "notes")
@ApiImplicitParam(paramType = "query", name = "param", value = "值",required = true, dataType = "string")
public String swagger(String param){
return param;
}
}
然后直接访问：http://localhost:8080/swagger-ui.html （端口和ip根据自己的配置来）
三、Swagger常用注解：
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
四、常见错误
- 项目启动起来了，发现访问http://localhost:8080/swagger-ui.html 的时候，出现了404。最后找到原因是Swager-ui的依赖没有导入进来。没有提示报错，如果出现此情况，需要自己去核对依赖是否正确引入！
- 如果配置类中添加了注解 @EnableWebMvc。为了避免覆盖了，Spring Boot resources 下的静态资源。采用如下代码：
@Configuration
@EnableSwagger2
@EnableAutoConfiguration
@EnableWebMvc
public class Swagger2Config extends WebMvcConfigurationSupport {
/**
*
* @return
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.iammn.controller"))
.paths(PathSelectors.any())
.build();
}
/**
*
* @return
*/
private ApiInfo apiInfo(){
Contact contact = new Contact("Swagger2 demo", "http://localhost", "邮箱");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTFUL API")
.description("描述信息")
.termsOfServiceUrl("http://localhost")
.version("1.0")
.contact(contact)
.build();
}
/**
* 防止@EnableMvc把默认的静态资源路径覆盖了，手动设置的方式
*
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
5、环境配置：
如果说我需要在dev环境开启swagger2的调试，而在生产环境关闭swagger2的调试，可以使用如下配置：
swagger:
enable: true
