一、Swagger2是什么？
为了减少程序员撰写文档时间，提高生产力， Swagger2 应运而生，使用 Swagger2 可以减少编写过多的文档，只需要通过代码就能生成文档API,提供给前端人员，非常方便。
二、添加依赖
<!-- swagger2 配置 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger2 官方前端UI -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger2 优化后的前端UI -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.5</version>
</dependency>
三、swagger2配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @Author Allens
* @Date 2020-01-14 15:13
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
// http://localhost:8088/swagger-ui.html 官方前端UI页面地址
// http://localhost:8088/doc.html 优化过的前端UI页面地址
//配置swagger2核心配置 docket
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) //指定api类型为swagger2
.apiInfo(apiInfo()) //用于定义api文档汇总信息
.select().apis(RequestHandlerSelectors.basePackage("com.allens.controller")) //指定controller包
.paths(PathSelectors.any()) //所用controller
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("电商平台接口api") //文档页标题
.contact(new Contact("allens","http://www.baidu.com","123@qq.com")) //联系人信息
.description("提供的api文档") //详细信息
.version("1.0.0") //文档版本号
.termsOfServiceUrl("https://www.baidu.com") //网站地址
.build();
}
}
四、注解标签使用
@ApiIgnore
在swagger文档中忽略掉该api@Api
在swagger中显示该api的相关信息
示例：
/**
* tags:api标题，如果添加了两个标题，这在swagger中会显示成两个分组，但包含的路由是同一组
*/
@Api(value = "登录相关", tags = {"用于用于注册登录的相关接口"})
-
@ApiOperation
在swagger中显示api下某个路由的相关信息
示例：
/**
* value:接口标题
* notes:接口的备注
* response:响应的类
* httpMethod:请求方式 值为："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" 和 "PATCH"。
* responseContainer:数据类型 值为："List", "Set" 或 "Map"。
*/
@ApiOperation(value = "用户注册", notes = "用户注册~", response = Users.class, httpMethod = "POST", responseContainer = "Map")
-
@ApiModel
在swagger中对于传参数据的注解
示例：
/**
* vale:数据类型
* description：参数说明
*/
@ApiModel(value = "用户对象BO", description = "从客户端，用用户传入的数据封装在此entity中")
-
@ApiModelProperty
在swagger中显示的传参中的属性的相关信息
示例：
/**
* value ： 在swagger中对于字段的注释
* name ：在swagger中对于字段的重写 不建议使用
* example ：字段的默认值
* required ：是否必传
*/
@ApiModelProperty(value = "密码", name = "confirm_password", example = "123455", required = true)
-
@ApiParam
针对参数所作的行为做的一个解释
示例：
public IMOOCJSONResult querySubCats(
/**
* name：参数名
* value：参数的作用的描述
* required：true或者false。表示是否必填
*/
@ApiParam(name = "rootCatId", value = "一级分类id", required = true)
@PathVariable Integer rootCatId) {
}
