版权声明：本文为博主原创文章，转载请注明链接地址。谢谢！ https://blog.csdn.net/wdy_2099/article/details/84255729
一. Swagger2简介
官网直达
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。方便前后端分离类型接口的功能查看，和实际体验，减少了后台和前端沟通的成本。
本文简单介绍了在Springboot项目中集成swagger2的方式，和一些常见问题。
二. Springboot 整合Swagger2
具体整合方法很简单：
（1）加入依赖
在 https://mvnrepository.com 网站上搜索springfox即可得到最新版本的依赖:
点进去选择对应版本的依赖包就可以了，高版本的依赖需要的springboot版本也高，这里需要特别注意哦。
这里用的是Springboot Dalston.SR2版本（也就是1.5.x版本）+ swagger 2.7.0版本：在pom.xml中引入以下依赖：
<!-- swagger2支持 -->
<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>
（2）配置Swagger2Config配置类：配置Swagger2的基本设置，【配置类和启动类放到同级】
package com.wdy;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* swagger2的配置文件，在项目的启动类的同级文件建立
*
* @author wangdy 2018年11月19日
*/
@Configuration
public class Swagger2Config extends WebMvcConfigurerAdapter {
// swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等，不然会扫描到spring一些api
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// 为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.wdy.web.controller")).paths(PathSelectors.any()).build();
}
// 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("SpringBoot 使用 Swagger2 构建RESTful API")
// 创建人
.contact(new Contact("wangdy", "https://blog.csdn.net/wdy_2099", ""))
// 版本号
.version("1.0.0")
// 描述
.description("API 描述文件").build();
}
/**
* 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
* 这个也是发生404的解决方案
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
（3）在启动类上加入@EnableSwagger2注解，在启动程序是启动Swagger2，如下图：
（4）启动程序，访问http://localhost:8060/swagger-ui.html 查看结果如下：
这样，springboot和swagger2的整合就完成了。
三. Swagger2常用API
常用的注解有3个，一个在方法上使用（），一个在实体的属性上使用，一个在参数上直接使用。
(1)在方法上使用:@ApiOperation(value=“对具体方法的功能描述”)
(2)参数是对象的情况：在对象的属性上使用:@ApiModelProperty(value=“对具体属性的功能描述”)
(3)参数是普通参数的情况：在参数上使用:@ApiParam(value=“对具体参数的功能描述”)
（4）效果展示：
这就是3个最常用的API了，就是对请求方法，其实就是参数的中文的详细的描述。
（5）其他注解说明：
@Api(): 作用于类，标识这个类是干嘛的，通常用于Controller层；
@Api(value="用户相关Controller",tags={"用户相关操作接口"})
@RestController
public class UserController{
//...
}
@ApiModel() 用于实体类，对于整个实体的描述；
@ApiModel(value="user对象",description="这是用户对象")
public class User{
//...
}
@ApiResponse 用于方法，描述操作的可能响应。
@ApiResponses: 用于方法，多种可能的响应集合
@ApiResponses(value = {
@ApiResponse(code = 500, message = "500:服务器错误"),
@ApiResponse(code = 500, message = "401:没有权限"),
@ApiResponse(code = 500, message = "100:系统错误")
})
至于其他API具体可以参考以下资料研究学习：
1）github: https://github.com/swagger-api
2）开放API :https://swagger.io/specification/