Swagger快速上手和使用

Swagger简介

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 官网：https://swagger.io/

SpringBoot集成Swagger

1. 导jar包

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2. 开启swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

3. 访问路径
   http://localhost:8080/swagger-ui.html
4. swagger界面
   

Swagger配置

1. 配置文档信息

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
//配置文档信息
@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
   //配置文档信息，swagger信息
   	   .apiInfo(apiInfo());
   //配置扫描接口信息，只会扫描controller的方法，生成接口文档，普通的类的方法不会扫描
   	   .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
       .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
       .paths(PathSelectors.ant("/kuang/**"))//一般PathSelectors.any() s扫描所有接口，也可以不配置.paths()方法；
      .build();
  }
}
//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

常用注解

• @Api(tags = “xxx模块说明”)

  作用在controller类上

• @ApiOperation(“xxx接口说明”)

  作用在controller接口方法上

• @ApiModel(“xxxPOJO说明”)

  作用在模型类上：如VO（返回值实体类）、DTO（参数实体类）

• @ApiModelProperty(value = “xxx属性说明”,hidden = true)

  作用在模型类属性上，hidden设置为true可以隐藏该属性

• @ApiParam(“xxx参数说明”)

  作用在controller接口方法参数上

注意，尽量不要使用注解name属性，别误导前端发错参数名