SpringBoot使用Swagger

快速在SpringBoot项目中集成Swagger

使用方法

1. 导入依赖

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

2. 使用注解

该注解可以用在任何类上, 案例中将其用在启动类上

@SpringBootApplication
@EnableSwagger
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

3. 配置

在进行了第二步之后, 已经可以正常使用Swagger, 各个属性都提供了默认值, 当然如果需要自己设置一些属性也可以, 所有属性如下:

• yml格式

swagger:
  contact:
    email: 联系邮箱
    name: 联系人昵称
    url: 联系人地址
  title: 标题
  description: 描述
  base-package: 接口所在包路径
  path-type: 接口选择规则类型, 共分为: ALL(所有接口), REGEX(符合正则), ANT(符合路径)三个类型, 默认为ALL类型
  path-pattern: 接口匹配规则,在path-type类型不为 "ALL" 的情况下必须设置,否则抛非法参数异常
  exclude-pattern: 排除路径，默认使用正则表达式方式，可在pathType设置为其他类型(pathType类型为ALL时默认走正则)
  terms-of-service-url: 服务条款
  license: 许可证
  license-url: 许可证地址

• JavaBean方式

@Configuration
public class DemoConfig {
    @Bean
    public SwaggerBean swaggerBean() {
        return SwaggerBean.builder()
                .basePackage("com.xxx.xxx")
                .pathType(PathType.ALL)
                .title("标题")
                .termsOfServiceUrl("http://127.0.0.1")
                .license("XXXX")
                .licenseUrl("http://xxx.xx.xx")
                .description("描述")
                .build();
    }
}     

4. 聚合文档

在实际工作中, 往往是多个服务的, 这样前端需要记住每个服务的地址, 显然太麻烦, 所以可以采用聚合文档模式, 将多个项目都聚合在一个服务里, 通常聚合在网关里, 毕竟每个服务都是走网关过得, 该模式限于SpringCloud环境, 且每个服务都在同一个注册中心下, 参考配置如下:

• yml格式

server:
  port: 8080
spring:
  application:
    name: zuul-server
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
zuul:
  routes:
    projectA:
      serviceId: web1
      path: /demo/**
swagger:
  resources:
    enable: 是否开启聚合模式, 默认 False
    register-me: 当前项目的文档是否也要加入聚合, 默认 true
    # 服务列表
    service-list:
      - projectA: 这里可以随便定义
          view: 下拉选择时展示的名字, 一般用于标识对应文档的名字
          service: 跟随zuul网关路由的path而定，如上为：/demo/**，那么这里应该填demo
      - projectB:
          view: 项目b
          service: demo  

• JavaBean方式

/**
 * @author Gjing
 **/
@Configuration
public class GatewayConfig {
    @Bean
    public SwaggerResources swaggerResources() {
        List<Map<String, SwaggerService>> serviceList = new ArrayList<>();
        Map<String, SwaggerService> service = new HashMap<>();
        service.put("projectA", SwaggerService.builder().view("项目A").service("demo").build());
        serviceList.add(service);
        return SwaggerResources.builder()
                .enable(true)
                .registerMe(true)
                .serviceList(serviceList)
                .build();
    }
}

更多信息可前往GitHub: tools-starter-swagger, 喜欢的小伙伴可以关注哦！