spring-boot-starter-swagger 1.2.0.RELEASE：新增分組配置功能簡介版本基礎如何使用參數配置

簡介

該項目主要利用Spring Boot的自動化配置特性來實作快速的将swagger2引入spring boot應用來生成API文檔，簡化原生使用swagger2的整合代碼。

• GitHub： https://github.com/dyc87112/spring-boot-starter-swagger
• 碼雲： http://git.oschina.net/didispace/spring-boot-starter-swagger
• 部落格： http://blog.didispace.com

小工具一枚，歡迎使用和Star支援，如使用過程中碰到問題，可以提出Issue，我會盡力完善該Starter

https://blog.didispace.com/spring-boot-starter-swagger-1.2.0/#%E7%89%88%E6%9C%AC%E5%9F%BA%E7%A1%80 版本基礎

• Spring Boot：1.5.x
• Swagger：2.7.x

https://blog.didispace.com/spring-boot-starter-swagger-1.2.0/#%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8 如何使用

在該項目的幫助下，我們的Spring Boot可以輕松的引入swagger2，主需要做下面兩個步驟：

• 在

  pom.xml

  中引入依賴：

<dependency>
    <groupId>com.didispace</groupId>
    <artifactId>spring-boot-starter-swagger</artifactId>
    <version>1.2.0.RELEASE</version>
</dependency>      

• 在應用主類中增加

  @EnableSwagger2Doc

  注解

@EnableSwagger2Doc
@SpringBootApplication
public class Bootstrap {

    public static void main(String[] args) {
        SpringApplication.run(Bootstrap.class, args);
    }

}      

預設情況下就能産生所有目前Spring MVC加載的請求映射文檔。

https://blog.didispace.com/spring-boot-starter-swagger-1.2.0/#%E5%8F%82%E6%95%B0%E9%85%8D%E7%BD%AE 參數配置

更細緻的配置内容參考如下：

https://blog.didispace.com/spring-boot-starter-swagger-1.2.0/#%E9%85%8D%E7%BD%AE%E7%A4%BA%E4%BE%8B 配置示例

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.1.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
[email protected]
swagger.base-package=com.didispace
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**      

配置說明

https://blog.didispace.com/spring-boot-starter-swagger-1.2.0/#%E9%BB%98%E8%AE%A4%E9%85%8D%E7%BD%AE 預設配置

- swagger.title=标題
- swagger.description=描述
- swagger.version=版本
- swagger.license=許可證
- swagger.licenseUrl=許可證URL
- swagger.termsOfServiceUrl=服務條款URL
- swagger.contact.name=維護人
- swagger.contact.url=維護人URL
- swagger.contact.email=維護人email
- swagger.base-package=swagger掃描的基礎包，預設：全掃描
- swagger.base-path=需要處理的基礎URL規則，預設：/**
- swagger.exclude-path=需要排除的URL規則，預設：空      

Path規則說明

swagger.base-path

和

swagger.exclude-path

使用ANT規則配置。

我們可以使用

swagger.base-path

來指定所有需要生成文檔的請求路徑基礎規則，然後再利用

swagger.exclude-path

來剔除部分我們不需要的。

比如，通常我們可以這樣設定：

management.context-path=/ops

swagger.base-path=/**
swagger.exclude-path=/ops/**, /error      

上面的設定将解析所有除了

/ops/

開始以及spring boot自帶

/error

請求路徑。

其中，

exclude-path

可以配合

management.context-path=/ops

設定的spring boot actuator的context-path來排除所有監控端點。

https://blog.didispace.com/spring-boot-starter-swagger-1.2.0/#%E5%88%86%E7%BB%84%E9%85%8D%E7%BD%AE 分組配置

當我們一個項目的API非常多的時候，我們希望對API文檔實作分組。從1.2.0.RELEASE開始，将支援分組配置功能。

具體配置内容如下：

- swagger.docket.<name>.title=标題
- swagger.docket.<name>.description=描述
- swagger.docket.<name>.version=版本
- swagger.docket.<name>.license=許可證
- swagger.docket.<name>.licenseUrl=許可證URL
- swagger.docket.<name>.termsOfServiceUrl=服務條款URL
- swagger.docket.<name>.contact.name=維護人
- swagger.docket.<name>.contact.url=維護人URL
- swagger.docket.<name>.contact.email=維護人email
- swagger.docket.<name>.base-package=swagger掃描的基礎包，預設：全掃描
- swagger.docket.<name>.base-path=需要處理的基礎URL規則，預設：/**
- swagger.docket.<name>.exclude-path=需要排除的URL規則，預設：空      

說明：

<name>

為swagger文檔的分組名稱，同一個項目中可以配置多個分組，用來劃分不同的API文檔。

分組配置示例

swagger.docket.aaa.title=group-a
swagger.docket.aaa.description=Starter for swagger 2.x
swagger.docket.aaa.version=1.2.0.RELEASE
swagger.docket.aaa.termsOfServiceUrl=https://gitee.com/didispace/spring-boot-starter-swagger
swagger.docket.aaa.contact.name=zhaiyongchao
swagger.docket.aaa.contact.url=http://spring4all.com/
[email protected]
swagger.docket.aaa.excludePath=/ops/**

swagger.docket.bbb.title=group-bbb
swagger.docket.bbb.basePackage=com.yonghui      

說明：預設配置與分組配置可以一起使用。在分組配置中沒有配置的内容将使用預設配置替代，是以預設配置可以作為分組配置公共部分屬性的配置。