一、介绍

功能

接口文档在线自动生成。
接口测试。 主要项目

1. Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
1. Swagger-core：用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
1. Swagger-js：用于JavaScript的Swagger实现。
1. Swagger-node-express：Swagger模块，用于node.js的Express web应用框架。
1. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
1. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

2.依赖2

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

三、配置类

package com.tongdatech.winterspring.wtyx.config;

import com.google.common.base.Predicates;
import com.google.common.collect.Lists;
import com.tongdatech.winterspringboot.pojo.Profiles;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.OAuth;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置类
 * 放在与Controller同级目录下
 * 通过@Configuration，让spring加载配置类
 * 通过@EnableSwagger2开启
 *
 */
@Configuration
@EnableSwagger2
public class wtyxSwaggerConfig {

    /**
     * 此处bean名称（方法名）是唯一的，不能重复，注意区分
     * 建议  包名+Docket
     * 
     * apiInof增加API相关信息。
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制哪些接口暴露给Swagger来展示
     */
    @Bean
    public Docket wtyxDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(Predicates.and(RequestHandlerSelectors.withClassAnnotation(Api.class),
                        RequestHandlerSelectors.basePackage("com.tongdatech.winterspring.wtyx")))
                .paths(PathSelectors.any())
                .build()
                .groupName("wtyx");
    }
    
    /**
     * 创建api信息在页面中展示
     *http://项目地址/swagger-ui.html
     *
     */
    private ApiInfo apiInfo = new ApiInfoBuilder().title("wty功能 - 接口测试").description("WinterSpring2 wtyx功能 - api")
            .version("0.0.1")
            .build();


}

2. 配置2

/**
 * @author: zek
 * @desc: swagger
 */
@EnableOpenApi
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)
        .pathMapping("/")
        // 定义是否开启swagger，false为关闭，可以通过变量控制
        .enable(true)
        // 将api的元信息设置为包含在json ResourceListing响应中。
        .apiInfo(apiInfo())
        // 接口调试地址
        .host("http://localhost:8080")
        // 选择哪些接口作为swagger的doc发布
        .select()
        .apis(RequestHandlerSelectors.basePackage("xx.xx.xx.controller"))
        .paths(PathSelectors.any())
        .build()
        // 支持的通讯协议集合
        .protocols(Sets.newHashSet("http", "https"))
        // 授权信息设置，必要的header token等认证信息
        .securitySchemes(securitySchemes())
        // 授权信息全局应用
        .securityContexts(securityContexts());
  }

  /** API 页面上半部分展示信息 */
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title(" Api Doc")
        .description("SpringFox 3.0.0 发布: https://xx.xx.xx/xx/swagger-ui/index.html")
        .contact(new Contact("lighter", null, "xx@163.com"))
        .version(
            "Application Version: "
                + "1.0.0"
                + ", Spring Boot Version: "
                + SpringBootVersion.getVersion())
        .build();
  }

  /** 设置授权信息 */
  private List securitySchemes() {
    ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
    return Collections.singletonList(apiKey);
  }

  /** 授权信息全局应用 */
  private List securityContexts() {
    return Collections.singletonList(
        SecurityContext.builder()
            .securityReferences(
                Collections.singletonList(
                    new SecurityReference(
                        "BASE_TOKEN",
                        new AuthorizationScope[] {new AuthorizationScope("global", "")})))
            .build());
  }

  /** 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息 */
  @SuppressWarnings("unchecked")
  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    try {
      Field registrationsField =
          FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
      List<InterceptorRegistration> registrations =
          (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
      if (registrations != null) {
        for (InterceptorRegistration interceptorRegistration : registrations) {
          interceptorRegistration
              .excludePathPatterns("/swagger**/**")
              .excludePathPatterns("/webjars/**")
              .excludePathPatterns("/v3/**")
              .excludePathPatterns("/doc.html");
        }
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

四、注解说明

@Api: 用在类上，说名类的作用。
@ApiOperation:用在方法上，说明方法的用途和作用。
@ApiParam:用在方法，参数和字段上，一般用在请求体上，描述请求体信息。
@ApiImplicitParams:用在请求的方法上，表示一组参数说明，里面是@ApiImplicitParam列表。
@ApiImplicitParam:用在 @ApiImplicitParams 注解中，一个请求参数的说明

@GetMapping("/page")
@ApiOperation(value = "分页查询问题列表")
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNum", value = "当前页数"),
    @ApiImplicitParam(name = "pageSize", value = "每页记录数")
})
public List<UserDTO> page(
    @RequestParam(defaultValue = "1", required = false) Integer pageNum, @RequestParam(defaultValue = "10", required = false) Integer pageSize) {
    return list;
}

@ApiResponse:用在 @ApiResponses 中，一般用于表达一个错误的响应信息。

@PutMapping
@ApiOperation(value = "更新用户信息")
@ApiResponses({
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
public Boolean update(@RequestBody @ApiParam(name = "UserDTO", value = "更新用户参数") UserDTO userDTO) {}

@ApiModel 用在实体类（模型）上，表示相关实体的描述。
@ApiModelProperty 用在实体类属性上，表示属性的相关描述。

注

1. entity中的@ApiModel注解中的参数加了和没加一个效果，所以，直接写@ApiModel就可以了。
1. @ApiParam(value = “文章ID”) 注解中的value参数只有和：@PathVariable(value = “id”) 以及@RequestParam使用，value参数才会有效果。其他没有

Swagger的使用

一、介绍

二、依赖

2.依赖2

三、配置类

2. 配置2

四、注解说明

注