Swagger

MR.XSS2023-04-192023-10-27

Swagger使用

简介

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

依赖

一：引入Swagger依赖库
<!--引入swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

配置文件

可以使用自带的配置类

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

也可以自己写

import com.google.common.base.Predicates;
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.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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                //调用apiInfo方法,创建一个ApiInfo实例,
                // 里面是展示在文档页面信息内容
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }


    // api文档的详细信息
    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("API文档接口测试")    //标题
                .description("本文档描述接口测试用例")  //描述
                .version("1.0")  //版本
                .contact(new Contact("java", "http://baidu.com", "123@qq.com"))
                .build();
    }
}

常用注解

用于类的注解

@Api：资源描述

相关属性：
- values：字符串；说明该类的作用，在类旁边的小字显示
- tags：字符串；标签（也可理解成分类），会替换 Controller 名称；当多个 Controller 的 tags 相同时，它们的方法会在一起显示
- consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json
- produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json
- hidden：true/false；隐藏整个 Controller，作用与 @ApiIgnore 相似，但没有 @ApiIgnore 功能强大
- protocols：字符串；标识当前的请求支持的协议，例如：http、https、ws
@ApiIgnore：资源过滤

有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解另一种是在 Docket 上增加筛选。两种方式的区别是，Docket 配置的规则，可以对多个接口器过滤作用，而 @ApiIgnore 只能作用于单个接口。
用于方法的注解

@ApiOperation：方法描述

属性：
- value：字符串；方法摘要，在路径旁显示
- note：字符串；方法详细描述
- tags：字符串数组；对方法进行分类，一个方法可以有多个分类
- response：Class；设置当前请求的返回值类型，String.class；会覆盖自动识别的返回类型，一般用不上
- responseContainer：字符串；说明包装的容器，默认情况下，有效值为 List、Set、Map；在定义通用 Response 后，一般用不上
- httpMethod：字符串；指定请求方式，比如 GET、POST、PUT
- consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json
- produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json
@ApiImplicitParam(s)：参数描述

参数描述，可用在方法头。

ApiImplicitParams 只有一个属性 ApiImplicitParam[] value(); 是 ApiImplicitParam 的数组
- name：字符串；参数名
- value：字符串；参数的汉字说明、解释
@ApiParam：参数描述

@ApiParam 的可以设置的属性如下：
- name：字符串；参数名
- value：字符串；参数的汉字说明、解释
关于 @ApiImplicitParam 和 @ApiParm 它俩都能为方法的请求参数做注释，区别有：

@ApiImplicitParam 可以在方法前使用，而 @ApiParm 只能在参数前使用
@ApiImplicitParam 提供的可设置属性更多，特别是 paramType 很关键
对于 @RequestBody 标识的 Json 字符串，不能使用 @ApiImplicitParam，会出现无法识别的情况
方案一：通过 @ApiParm 对 @RequestBody 的参数进行说明
方案二：直接不对该参数使用注解，将注释的任务交给实体类（@ApiModel）
另外，两者是可以混搭使用的，一般推荐使用 @ApiImplicitParam(s)，但是注意 @RequestBody 的情况。

3.用于实体类的注解

@ApiModel：实体类描述

@ApiModel 可以设置的属性有：

@ApiModelProperty：实体类成员描述

使用knife4j来代替swagger

导入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

进行配置

package com.xu.common.config.knife4j;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;
import java.util.List;

/**
 * knife4j配置信息
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {

    @Bean
    public Docket adminApiConfig(){
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("token")
                .description("用户token")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());
        //添加head参数end

        Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .apis(RequestHandlerSelectors.basePackage("com.xu"))
                .paths(PathSelectors.regex("/admin/.*"))
                .build()
                .globalOperationParameters(pars);
        return adminApi;
    }
}