SpringBoot集成Swagger3

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;
    }

}
上一篇:springboot 整合swagger2 启动控制台报错 Failed to start bean 'documentationPluginsBootstrapper',空指针


下一篇:第一次使用Swagger出现空指针异常