Swagger简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

官网：swagger.io

Swagger解决的痛点

传统方式提供文档有以下痛点：

• 接口众多，实现细节复杂，编写文档耗费费力，需要持续维护；
• 接口文档需要随时进行同步；
• 接口返回的结果不明确，得构造返回结构体等；
• 不能直接在线测试接口，通常需要额外的工具，比如PostMan等。

当引入Swagger之后，以上痛点迎刃而解，同时还带来以下优点：

• 及时性 (接口变更后，前后端人员可实时看到最新版本)
• 规范性 (接口具体统一风格，如接口地址，请求方式，参数，响应格式和错误信息等)
• 一致性 (接口信息一致，不会因接口文档版本问题出现分歧)
• 可测性 (可直接基于接口文档进行测试)

Swagger3的改变

Swagger3.0的改动，官方文档总结如下几点：

• 删除了对springfox-swagger2的依赖；
• 删除所有@EnableSwagger2...注解；
• 添加了springfox-boot-starter依赖项；
• 移除了guava等第三方依赖；
• 文档访问地址改为http://ip:port/project/swagger-ui/index.html。

在SpringBoot项目导入对应的依赖

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <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>

指定配置文件

通常情况下swagger只能在开发环境或测试环境下开启，生产环境下需要进行关闭的。而swagger的开启与关闭可在application.yml中进行配置：

# 生产环境需设置为false
springfox:
  documentation:
    swagger-ui:
      enabled: true

配置类

通过@EnableOpenApi注解启动用Swagger的使用，同时在配置类中对Swagger的通用参数进行配置。

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

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

@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Bean
    public Docket createRestApi() {
        //返回文档摘要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }

    /**
     * 生成接口信息，包括标题、联系人等
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("Swagger文档")
                .contact(new Contact("杜嘟嘟", "https://www.choupangxia.com/", "664121181@qq.com"))
                .version("1.0")
                .build();
    }

    /**
     * 封装全局通用参数
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("uuid")
                .description("设备uuid")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * 封装通用响应信息
     */
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("未找到资源").build());
        return responseList;
    }

}