Java学习笔记--Swagger2

一、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) {
        
}