@TOC
引言
在前后端开发过程中，为了减少前后端程序员以及与其他团队之间的沟通成本，因此要定义一组公共的API接口文档来描述所有接口方法的信息。但是这种方式在某一方面也存在很大的弊端，如下：
- 如果开发人员所描写的接口数量众多，一方面编写API接口文档工作量巨大，另一方面因为API接口不仅包含接口的基础信息，例如：请求参数‘请求类型及接口的返回值等等，还要包含HTTP请求类型，请求头、请求参数类型等；
- 后期维护不方便，一旦编写的接口发生变化，就要修改此API接口文档；
- 接口测试不方便，一般只能靠第三方客户端来测试
一、Swagger 2简介
Swagger 2是一个开源的软件框架，可以帮助开发人员设计、构建和使用Web服务，将代码与文档结合在一起，完美的解决了上述问题，使开发人员将大部分精力集中到业务中，而不是文档的撰写。
二、SpringBoot集成Swagger
2.1引入Swagger的依赖
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<scope>compile</scope>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<scope>compile</scope>
<version>2.9.2</version>
</dependency>2.2编写Swagger 2配置类
package com.org.comunity.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.org.comunity"))
.build().apiInfo(new ApiInfoBuilder().description("xxxx管理系统")
.contact(new Contact("xxx", "https://www.xxx.com", "xxxx@163.com"))
.version("V1.0").title("API测试文档")
.license("Apache2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.build());
}
}==解释:==
RequestHandler=Selectors.basePackage(“com.org.comunity”)
com.org.comunity为所要扫描的控制器即接口
2.3编写控制器类测试
package com.org.comunity.controller;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class RootController {
@ApiOperation("测试")
@RequestMapping("/hello")
public String test(){
return "Hello World!";
}
}==Swagger 2注解解释==
注解 作用 参数 ==@Api== 表示标识这个类是swagger的资源 1.tags=”说明该类的作用，可以在UI界面上看到的注解”
2.value=”该参数没什么意义，在UI界面上也看到，所以不需要配置”==@ApiOperation== 用在请求的方法上，说明方法的用途、作用，表示一个http请求的操作 value=”说明方法的用途、作用”
notes=”方法的备注说明”@ApiImplicitParams 用在请求的方法上，表示一组参数说明，用于方法，包含多个 @ApiImplicitParam name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明@ApiImplicitParam 用在@ApiImplicitParams注解中，指定一个请求参数的各个方面，表示单独的请求参数 name：参数的汉字说明、解释
value：参数名
required：参数是否必须传
paramType：参数放在哪个地方
header： 请求参数的获取：==@ApiIgnore== 用于类，方法，方法参数表示这个方法或者类被忽略 ,可以不被swagger显示在页面上 @RequestHeader 指定请求类型 query：请求参数的获取： @ApiParam 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等 name–参数名
value–参数说明
required–是否必填@PathVariable 是获取get方式，url后面参数，进行参数绑定，对应path body（不常用）form（不常用） dataType：参数类型，默认String，其它值dataType=”Integer” defaultValue：参数的默认值 @ApiResponses 用在请求的方法上，表示一组响应 code http的状态码
message 描述
response 默认响应类 Void
reference 参考ApiOperation中配置
responseHeaders 参考 ResponseHeader 属性配置说明
responseContainer 参考ApiOperation中配置@ApiResponse 用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类==@ApiModel== 用于响应类上，表示一个返回响应数据的信息这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候)表示对类进行说明，用于参数用实体类接收 暂无 @ApiModelProperty 表示对model属性的说明或者数据操作更改 value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏==@ResponseHeader== 用于方法上，设置响应头 name 响应头名称
description 头描述
response 默认响应类 Void
responseContainer 参考ApiOperation中配置
==黄色为常用注解==
2.4启动应用访问swagger-ui
浏览器输入 http://localhost:8086/swagger-ui.html
8086为你的应用启动的端口号
==用法：==
以上就是SpringBoot集成Swagger 2的全部了，希望大家能够get，有问题请及时批评斧正！！！
