SpringBoot、SpringCloud项目使用Swagger接口文档

快速在SpringBoot、SpringCloud项目中集成Swagger接口文档，SpringBoot版本建议2.2.x+

一、添加依赖

建议前往文档查看最新版本

<dependency>
     <groupId>cn.gjing</groupId>
     <artifactId>tools-starter-swagger</artifactId>
     <version>2.0.2</version>
</dependency>

提示

如果项目中有设置拦截器或者引入了带有拦截器的第三方依赖，那么需要给每个拦截器配置排除Swagger的     
相关路径: /error, /v2/**, /v3/**, /**/doc.html,  /webjars/**, /swagger-ui/**, /swagger-resources/**

二、注解说明

1、@EnableSingleDoc

在启动类上使用，开启SpringBoot项目接口文档

2、@EnableGroupDoc

在启动类上使用，开启SpringCloud项目文档聚合，一般使用在网关项目

三、SpringBoot项目配置明细

如下为全部配置参数，在项目中可选择自己需要的参数进行配置

tools:
  doc:
    contact:
      # 联系邮箱
      email:
      # 联系人昵称
      name:
      # 联系人地址
      url:
    # 是否开启文档，默认true，生产环境可以通过变量设置关闭
    enable: true
    # 标题
    title:
    # 描述
    description:
    # 接口所在包路径，如果未填写会默认找所有带了@ApiOperation注解的接口
    base-package:
    # 接口选择规则类型, 共分为: REGEX(正则匹配), ANT(路径匹配), 默认ANT
    path-type:
    # 接口匹配规则表达式
    path-pattern:
    # 接口排除匹配表达式
    exclude-pattern:
    # 服务条款
    terms-of-service-url:
    # 许可证
    license:
    # 许可证地址
    license-url:
    # 全局响应信息
    global-response-schemas:
      # 状态码
      - code: 200
        # 响应信息
        message: 正常
        # 结果Bean的类名
        schema: ResultVO
      - code: 400
        message: 错误
    # 全局请求参数，设置会为每一个方法加上此参数
    global-parameters:
      # 请求头名称
      - name: token
        # 请求头描述
        desc: 登录的token
        # 是否必须, 默认为false
        required: true

SpringBoot项目配置案例

# 接口文档
spring:
  application:
    name: doc-demo
# 如果不需要配置扫描包，那么可以不用配置其他的，直接全部走默认的即可
tools:
  doc:
    # 一般配置好扫描的controller包路径就好了，
    base-package: com.xxx.xxx.controller
    title: 文档API

注意事项：

方法返回值为void时，设置状态码为200的schema才有效，否则会采用方法本身的返回值，如需自定义，必须采用方法上使用@ApiResponses进行设置的方式，其他的状态码就没啥关系
全局返回值全局配置的方式优先级小于方法或者类单独配置的方式
全局配置返回值方式无法更改状态码为200的提示信息，如需更改必须采用在方法或者类上配置@ApiResponses的方式
配置全局参数会出现在所有方法里面，不与你在某个方法单独加个请求头冲突，两者会合并

四、SpringCloud环境配置案例

1、Zuul网关

其他子服务均需要引入kit-doc依赖并开启了接口文档，且与Zuul在同一个注册中心下

server:
  port: 8080
spring:
  application:
    name: zuul
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
zuul:
  routes:
    projectA:
      serviceId: demo
      path: /demo/**
# 文档配置
tools:
  doc:
    group:
      # 开启聚合文档
      enable: true
      # 服务列表
      service-list:
        # 下拉选择时展示的名称
        - desc: 项目A
          # route中配置的path参数非**的部分
          target: demo
          # 如果目标服务配置了servlet.context-path，那么也需要在此进行配置
          contextPath: xxx

2、SpringCloud Gateway网关配置案例

与使用Zuul时配置的相同，其他子服务均需要引入kit-doc依赖并开启了接口文档，且与GateWay在同一个注册中心下

server:
  port: 8080
spring:
  application:
    name: gateway
  cloud:
    gateway:
      routes:
        # 路线ID
        - id: demo
          # 目标URI，可以使用lb://服务名
          uri: lb://demo
          # 断言
          predicates:
            - Path=/demo/**
          # 过滤器集合
          filters:
            # 去除路由后的前缀
            - StripPrefix=1
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true
    instance-id: gateway
# 文档配置
tools:
  doc:
    group:
      enable: true
      # 服务列表
      service-list:
        # 下拉选择时展示的名称
        - desc: 项目A
          # route中配置的path参数非**的部分
          target: demo

使用GateWay作为网关时，需要在每个子服务中eureka中增加如下配置，否则路由失败

eureka:
  instance:
    # 不使用主机名来定义注册中心的地址，而使用IP地址的形式
    prefer-ip-address: true
    # 这个随便命名
    instance-id: xxx

配置好后可以根据地址：http://ip:port/doc.html（bootstrap UI）或者 http://ip:port/swagger-ui/index.html（原生UI）进行访问

五、效果图

1、全局响应信息以及全局请求头

rh.png

2、SpringBoot项目开启接口文档效果

image.png

3、SpringCloud项目网关项目开启聚合效果

与SpringBoot开启文档一样，只不过可以在左上角的下拉框进行选择路由到其他服务

route.png

4、原生UI效果