参考博客:https://blog.csdn.net/sanyaoxu_2/article/details/80555328
https://blog.csdn.net/forezp/article/details/71023536
一、简介
Swagger是一款Restful接口的文档在线自动生成+功能测试的软件。
Swagger是一个规范和完整的框架。用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统
作为服务器以同样的速度 来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.
二、Swagger2常用api注解
@Api:用在类上,说明该类的作用
@ApiOperation:用在方法上,说明方法的作用
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
paramType:参数放在哪个地方
header–>请求参数的获取:@RequestHeader
query–>请求参数的获取:@RequestParam
path(用于restful接口)–>请求参数的获取:@PathVariable
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例 如”请求参数没填好”
response:抛出异常的类
@ApiModel:描述一个Model的信息(
@ApiModelProperty:描述一个model的属性
三、使用步骤
1、添加pom依赖
<!-- SpringBoot整合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>
注意:guava的jar版本必须20以上,否则启动缺少相关jar依赖
2、新增Swagger的配置类
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.produces(Sets.newHashSet("application/json"))
.consumes(Sets.newHashSet("application/json"))
.protocols(Sets.newHashSet("http", "https"))
// 文档说明
.apiInfo(apiInfo()).select()
// 指定controller存放的目录路径
.apis(RequestHandlerSelectors.basePackage("com.test.index.controller"))
.paths(PathSelectors.any())
.build();
}
// 构建api文档的详细说明
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 文档标题
.title("springBoot集成Swagger2构建RESTful API")
// 创建人
.contact(new Contact("test", "http://www.baidu.com", ""))
// 版本号
.version("1.0")
// 文档描述
.description("API 描述").build();
}
}
3、新增swagger-ui.html的静态资源路径映射,解决访问swagger-ui.htm页面404问题
SpringBoot自动配置本身并不会把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面,需要配置
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
4、查看文档:http://ip:端口/项目路径/swagger-ui.html