SpringBoot快速集成Swagger

快速在SpringBoot項目中集成Swagger

使用方法

1. 導入依賴

<dependency>
     <groupId>cn.gjing</groupId>
     <artifactId>tools-starter-swagger</artifactId>
     <version>1.1.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格式

swagger:
  resources:
    enable: 是否開啓聚合模式, 默認 False
    register-me: 當前項目的文檔是否也要加入聚合, 默認 true
    # 服務列表
    service-list:
      - projectA: 這裏可以隨便定義
          view: 下拉選擇時展示的名字, 一般用於標識對應文檔的名字
          service: 服務名
      - projectB:
          view: 項目b
          service: demo2   

• 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, 喜歡的小夥伴可以關注哦！