Swagger知识总结

一、Swagger简介

      简单来说，Swagger就是在前后端分离的项目中帮助后台开发人员动态生成接口文档的工具，使得后台开发人员不用再去手写接口文档，大大节约了后台开发人员的时间。

二、Swagger快速入门

Swagger一般是集成在SpringBoot项目中使用的，所以我们需要在SpringBoot项目中配置它。

1. 在pom文件中导入坐标依赖: 其中，第一个坐标是Swagger的依赖；第二个是Swagger-ui的依赖，它的作用是使用可视化 UI 来展示接口文档。

        <!--Swagger 依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--Swagger-ui 依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2. 创建一个实体类: 用于测试

public class People {

    private int id;
    private String name;
    private String address;

    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getAddress() {
        return address;
    }
    public void setAddress(String address) {
        this.address = address;
    }
}

3. 创建用于测试的Controller

@Controller
public class DemoController {
    @RequestMapping("test")
    @ResponseBody
    public People getPeople(int id, String name, String address){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress(address);
        return people;
    }
}

4. 在SpringBoot的启动类上加注解 @EnableSwagger2
5. 运行后通过 http://ip:port/swagger-ui.html即可以访问到 swagger-ui 页面,这个界面就是swagger-ui工具帮助我们生成的。效果如下:
   

点击demo-controller可以看到我们刚刚编写的测试接口，只是因为我们没有指定该接口是通过什么方式来请求，所以它为这个接口生成了不同请求方式的文档。

而Model中也有我们编写的实体类，因为我们的接口的返回值是这个实体类，所以可以扫描到它。

6. 使用Swagger请求接口

点击一个接口进入界面，然后点击try it out

输入参数进行运行

查看返回结果

至此，快速入门就结束啦

三、Swagger的配置

1. 配置基本信息

• 基本对象与方法介绍：
  Docket： 摘要对象，通过对象配置描述文件的信息。
  apiInfo: 设置描述文件中 info。参数类型 ApiInfo
  select(): 返回 ApiSelectorBuilder 对象，通过对象调用 build()可以 创建Docket 对象
  ApiInfoBuilder： ApiInfo 构建器。
• 编写配置类：

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //getApiInfo()是下面的方法, 在该方法的返回的对象中配置信息
                .apiInfo(getApiInfo())
                .select()
                .build();
    }

    private ApiInfo getApiInfo(){
        return new ApiInfoBuilder().title("这里是标题")
                                   .description("这里是描述信息")
                                   .version("这里是版本--->1.0.0")
                                   .contact(new Contact("联系人","http://www.baidu.com","116@qq.com"))
                .build();
    }
}

效果如下:

2. 设置扫描的包

可以通过apis方法设置扫描的包

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //getApiInfo()是下面的方法, 在该方法的返回的对象中配置信息
                .apiInfo(getApiInfo())
                .select() 
                //只扫描配置的这个包
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))  
                .build();
    }

3.通过正则表达式配置要生成文档的路径

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //getApiInfo()是下面的方法, 在该方法的返回的对象中配置信息
                .apiInfo(getApiInfo())
                .select()
                //匹配路径满足这样的规则才会生成接口文档
                .paths(PathSelectors.regex("/test/*"))  
                .build();
    }

这里表示只有以/test开头的接口才会生成文档

四、Swagger常用注解

1. Api:

• @Api 是类上的注解。控制整个类生成接口信息的内容。
• tags：类的名称。可以有多个值，多个值表示多个副本。
• description:描述，已过时。

@Controller
@Api(tags={"Demo控制器"},description = "类的描述")
public class DemoController {
}

2. ApiOperation:

• @ApiOperation 写在方法上，对方法进行总体描述
• value：接口描述
• notes：提示信息

@ApiOperation(value = "接口描述",notes = "接口提示信息(一般是大段的描述)")

3. ApiParam:

• @ApiParam 写在方法参数前面。用于对参数进行描述或说明是否为必添项等。
• name：参数名称
• value：参数描述
• required：是否是必须

public People getPeople(int id, @ApiParam(name = "参数名称",value = "参数描述",required = true) String name, String address){}

4. ApiModel:

• @ApiModel 是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。
• value：名称
• description：描述

@ApiModel(value = "Model名称",description = "Model描述")
public class People {

5. ApiModelProperty:

• @ApiModelProperty 可以用在类的属性上。用于当对象作为参数时定义这个字段的内容。
• value：描述
• name：重写属性名
• required：是否是必须的
• example：示例内容
• hidden：是否隐藏。

比如，此时people是该方法的参数

    @RequestMapping("ignore")
    @ResponseBody
    public People ignoreInstance(People people){
        return people;
    }

id字段上加上注解

public class People {
    @ApiModelProperty(value = "主键id",name = "id",required = true,example = "100") 
    private int id;
    private String name;
    private String address;
}

在接口中的效果：

在Model中的效果：

6. ApiIgnore

• @ApiIgnore 用于方法或类或参数上，表示这个方法或类被忽略。

7. ApiImplicitParam

• @ApiImplicitParam 用在方法上，表示单独的请求参数，总体功能和@ApiParam 类似。
• name：属性名
• value：描述
• required：是否是必须的
• paramType：属性类型
• dataType：数据类型

    @ApiImplicitParam(name = "id",value = "主键id",required = true,dataType = "",paramType = "")
    @RequestMapping("ApiImplicitParamTest")
    @ResponseBody
    public People apiImplicitParamTest(int id, String name, String address){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress(address);
        return people;
    }

也可以同时添加多个属性的信息

    @ApiImplicitParams(value = {
         @ApiImplicitParam(name = "id",value = "主键id",required = true,dataType = "string",paramType = "query")
        ,@ApiImplicitParam(name = "name",value = "姓名",required = false)}
    )
    @RequestMapping("ApiImplicitParamTest")
    @ResponseBody
    public People apiImplicitParamTest(int id, String name, String address){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress(address);
        return people;
    }