Swagger2学习笔记

Swagger2

Swagger2 整合 Springboot

地址：https://blog.csdn.net/simba1949/article/details/80919183

什么是swagger2

编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

Swagger2 配置类

代码

package top.simba1949.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 配置类
 * @Configuration 让 Spring 容器加载该配置类
 * @EnableSwagger2 用于启动 swagger2
 * @author [email protected]
 * @date 2018/7/4 21:36
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * swagger2 启动后，通过createRestApi函数创建Docket的Bean，
     * apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
     * select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("top.simba1949.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("springboot学习笔记")
                .termsOfServiceUrl("http://localhost:8080/")
                .version("1.0")
                .build();
    }

}

效果

常用注解

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

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

• @ApiParam：单个参数描述

• @ApiModel：用对象来接收参数

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

• @ApiIgnore：使用该注解忽略这个API，用于类或者方法上

• @ApiImplicitParam：一个请求参数，用于方法上

• @ApiImplicitParams：多个请求参数 ，包含多个 @ApiImplicitParam，用于方法上

  扫描二维码关注公众号，回复： 2189674 查看本文章

  @Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解，如果tags多个值，会生成多个list"
    value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"
  
  @ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
  
  @ApiParam：单个参数描述
  - name：参数名
  - value：参数说明
  - required：是否必填
  
  @ApiModel：用对象来接收参数
  - value：表示对象名
  - description：对对象的描述
  @ApiModelProperty：用对象接收参数时，描述对象的一个字段
    - value：字段说明
    - name：重写属性名
    - dataType：重写属性类型
    - example：举例说明
    - hidden：隐藏
  
  @ApiIgnore：使用该注解忽略这个API，用于类或者方法上
  
  @ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@Api：

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

• @Api
  
  • tags：对类的说明

代码

/**
 * @Api 
 * value="不会再界面显示出来"
 * tags="说明该类的作用，可以在UI界面上看到的注解，如果tags多个值，会生成多个list"
 * @date 2018/7/4 20:17
 */
@Api(tags = {"用户操作接口"})
@Controller
@RequestMapping("/user")
public class UserController {

}

效果

@ApiOperation:

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

• @ApiOperation
  
  • value：用于方法描述
  • notes：用于提示内容

代码

@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@PathVariable String data){
    return ResponseBuilder.buildSuccessResponse(data);
}

效果

@ApiParam：

用于单个参数描述

• @ApiParam
  
  • name：参数名
  • value：参数说明
  • required：是否必填

代码

@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@ApiParam(name = "data",value = "参数说明",required = true)@PathVariable String data){
    return ResponseBuilder.buildSuccessResponse(data);
}

效果

@ApiModel & @ApiModelProperty

@ApiModel：用对象来接收参数

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

• @ApiModel：用对象来接收参数
  
  • value：表示对象名
  • description：对对象的描述
• @ApiModelProperty：用对象接收参数时，描述对象的一个字段
  
  • value：字段说明
  • name：重写属性名
  • dataType：重写属性类型
  • example：举例说明
  • hidden：隐藏

代码

package top.simba1949.common;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @author [email protected]
 * @date 2018/7/4 20:18
 */
@ApiModel(value = "用户的POJO",description = "对对象的描述")
public class UserCommon {

    @ApiModelProperty(value = "用户Id",name = "userId",dataType = "int",required = true,example = "1",hidden = true)
    private int userId;
    @ApiModelProperty(value = "用户名",name = "username",dataType = "String",required = true,example = "李白")
    private String username;
    @ApiModelProperty(value = "用户年龄",name = "age",dataType = "int",required = true,example = "888")
    private int age;
    @ApiModelProperty(value = "用户密码",name = "password",dataType = "String",required = true,example = "19491001")
    private String password;

    // getter/setter方法省略
}

效果

@ApiIgnore：

使用该注解忽略这个API，用于类或者方法上

@ApiImplicitParams & @ApiImplicitParam

@ApiImplicitParams ：多个请求参数 ，用于方法上，包含多个 @ApiImplicitParam

@ApiImplicitParam：一个请求参数，用于方法上

• @ApiImplicitParam
  
  • name：参数名
  • value：参数说明
  • dataType：参数类型，默认String，其他值dataType=”Integer”
  • paramType：参数发在哪个地方
  • header：请求参数的获取 @RequestHeader
  • query：请求参数的获取 @RequestParam
  • path：请求参数的获取 @PathVariable
  • body（不常用）
  • form （不常用）
  • required：是否必须填写
  • defaultValue：默认值

代码

@ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法，提示内容")
@ApiImplicitParams({
    @ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),
    @ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
})
@PostMapping("/query/{data}/{i}")
@ResponseBody
public ResponseCommon query(@PathVariable String data,@PathVariable int i){
    return ResponseBuilder.buildSuccessResponse(data + i);
}

效果