spring-boot-starter-swagger 1.2.0.RELEASE：新增分組配置功能

轉自：http://blog.didispace.com/spring-boot-starter-swagger-1.2.0/

簡介

該項目主要利用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

版本基礎

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

如何使用

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

• 在pom.xml中引入依賴：

1 2 3 4 5

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

• 在應用主類中增加@EnableSwagger2Doc註解

1 2 3 4 5 6 7 8 9

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

默認情況下就能產生所有當前Spring MVC加載的請求映射文檔。

參數配置

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

配置示例

1 2 3 4 5 6 7 8 9 10 11 12

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/**

配置說明

默認配置

1 2 3 4 5 6 7 8 9 10 11 12

- 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來剔除部分我們不需要的。

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

1 2 3 4

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來排除所有監控端點。

分組配置

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

分組功能

具體配置內容如下：

1 2 3 4 5 6 7 8 9 10 11 12

- 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文檔。

分組配置示例

1 2 3 4 5 6 7 8 9 10 11

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

說明：默認配置與分組配置可以一起使用。在分組配置中沒有配置的內容將使用默認配置替代，所以默認配置可以作爲分組配置公共部分屬性的配置。