Swagger详解

1、Swagger的介绍

1.1 Swagger的工作原理

　　1、系统启动，扫描到api工程中的Swagger2Configuration类

　　2、在此类中指定了包路径，会找到在此包下及子包下标记有@RestController注解的controller类

　　3、根据controller类中的Swagger注解生成接口文档。

1.2 Swagger中常用的注解

　　@Api：修饰整个类，描述Controller的作用

　　@ApiOperation：描述一个类的一个方法，或者说一个接口

　　@ApiParam：单个参数描述

　　@ApiModel：用对象来接收参数

　　@ApiModelProperty：用对象接收参数时，描述对 象的一个字段

　　@ApiResponse：HTTP响应其中1个描述

　　@ApiResponses：HTTP响应整体描述

　　@ApiIgnore：使用 该注解忽略这个API

　　@ApiError ：发生错误返回的信息

　　@ApiImplicitParam：一个请求参数，这个请求参数可以为空

　　@ApiImplicitParams：多个请求参数

　　参照： https://www.cnblogs.com/fengli9998/p/7921601.html

2、SpringBoot项目下如何生成Swagger接口文档

2.1引入Swagger依赖

 1 <dependency>
 2     <groupId>io.springfox</groupId>
 3     <artifactId>springfox-swagger2</artifactId>
 4     <version>2.7.0</version>
 5 </dependency>
 6 <dependency>
 7     <groupId>io.springfox</groupId>
 8     <artifactId>springfox-swagger-ui</artifactId>
 9     <version>2.7.0</version>
10 </dependency>   

2.2添加Swagger2Configuration类

 1 @Configuration
 2 @EnableSwagger2
 3 public class Swagger2Configuration {
 4
 5     @Bean
 6     public Docket createRestApi() {
 7         return new Docket(DocumentationType.SWAGGER_2)
 8                 .apiInfo(apiInfo())
 9                 .select()
10                 .apis(RequestHandlerSelectors.basePackage("......"))
11                 .paths(PathSelectors.any())
12                 .build();
13     }
14
15     private ApiInfo apiInfo() {
16         return new ApiInfoBuilder()
17                 .title("XXX")
18                 .description("XXXXXX")
19 //                .termsOfServiceUrl("/")
20                 .version("1.0")
21                 .build();
22     }
23 }

2.3 在类上添加Swagger注解

2.3.1 Controller上注解

 1 @Api(value="测试Controller",tags={"用户操作接口"})
 2 @RestController
 3 public class TestController {
 4
 5     @PostMapping("/test")
 6     @ApiOperation(value="此接口用于测试Swagger")
 7     @ApiImplicitParams(
 8             {
 9                     @ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int")
10                     ,@ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")
11             })
12     public ResponseData<Object> test(int page,int size, @RequestBody ItemListReq itemListReq) throws IOException, JSONException {
13
14         ResponseData responseData = new ResponseData();
15
16         return responseData;
17     }
18
19 }

2.3.2 实体类上注解

@Data
public class ItemListReq {

    //页码 从0开始
    @ApiModelProperty("页码 从0开始")
    int pageNo =0 ;

    //单页返回的记录数
    @ApiModelProperty("单页返回的记录数,默认值10")
    int pageSize = 10 ;

    //标准商品编号
    @ApiModelProperty("标准商品编号")
    String itemId;

    //标准商品名称,支持不带特殊字符的模糊匹配
    @ApiModelProperty("标准商品名称,支持不带特殊字符的模糊匹配")
    String itemName;

}

2.3.3 效果（服务地址ip:port/swagger-ui.html）

1.

2.