天天看點
傳回

久違了，更新一波 swagger starter！更新内容如何使用參數配置

這個swagger的starter已經存在四年了，記得當時做這個的時候主要是由于swagger官方并沒有提供類似spring boot官方其他starter子產品一樣的封裝。當我們要用swagger的時候，還是要寫很多Java配置來啟動，是以就做了這個，盡可能的把原來要寫在Java中的配置都轉移到配置檔案中來。

一個小小的封裝，也獲得了2k+的Star，使用也超過了3.1k。

久違了，更新一波 swagger starter！更新内容如何使用參數配置
之前由于springfox 3.0推出了starter（之前我也寫了篇部落格介紹 使用SpringFox 3生成Swagger文檔

），想着既然有了這個，那就沒有花太多精力去繼續更新了。

但是，一直有收到用過springfox starter的小夥伴反應還是希望可以用純配置的方式來使用swagger，希望這個swagger可以繼續更新到最新的版本。是以，下面會繼續跟進這個starter，這裡要特别感謝andi.lin（

https://github.com/llin6025）的積極參與，得以讓這次的更新繼續進行。 倉庫位址： https://github.com/SpringForAll/spring-boot-starter-swagger

https://blog.didispace.com/swagger-starter-2-release/#%E6%9B%B4%E6%96%B0%E5%86%85%E5%AE%B9 更新内容

  • 更新依賴的springfox swagger到3.0.0
  • 文檔的開啟關閉控制改為springfox.documentation.enabled參數

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

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

  • 在

    pom.xml

     中引入依賴： 
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.0.0.RELEASE</version>
</dependency>

**注意

  1. 從

    1.6.0

     開始，我們按Spring Boot官方建議修改了artifactId為

    swagger-spring-boot-starter

     ，1.6.0之前的版本不做修改，依然為使用

    spring-boot-starter-swagger

     !**

  2. 2.0.0

     開始，不再需要手工添加

    @EnableSwagger2Doc

     來啟動Swagger配置

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

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

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

springfox.documentation.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.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/**

swagger.globalOperationParameters[0].name=name one
swagger.globalOperationParameters[0].description=some description one
swagger.globalOperationParameters[0].modelRef=string
swagger.globalOperationParameters[0].parameterType=header
swagger.globalOperationParameters[0].required=true
swagger.globalOperationParameters[1].name=name two
swagger.globalOperationParameters[1].description=some description two
swagger.globalOperationParameters[1].modelRef=string
swagger.globalOperationParameters[1].parameterType=body
swagger.globalOperationParameters[1].required=false

// 取消使用預設預定義的響應消息,并使用自定義響應消息
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

配置說明

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

springfox.documentation.enabled=是否啟用swagger，預設：true

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規則，預設：空

swagger.host=文檔的host資訊，預設：空

swagger.globalOperationParameters[0].name=參數名
swagger.globalOperationParameters[0].description=描述資訊
swagger.globalOperationParameters[0].modelRef=指定參數類型
swagger.globalOperationParameters[0].parameterType=指定參數存放位置,可選header,query,path,body.form
swagger.globalOperationParameters[0].required=指定參數是否必傳，true,false

1.3.0.RELEASE

新增：

swagger.host

屬性，同時也支援指定docket的配置

1.4.0.RELEASE

  • swagger.enabled

     ：用于開關swagger的配置

  • swagger.globalOperationParameters

     ：用于設定全局的參數，比如：header部分的accessToken等。該參數支援指定docket的配置。

2.0.0.RELEASE

 調整：
  • 原來的

    swagger.enabled

     配置修改為

    springfox.documentation.enabled

     來控制

https://blog.didispace.com/swagger-starter-2-release/#Path%E8%A7%84%E5%88%99%E8%AF%B4%E6%98%8E 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/swagger-starter-2-release/#%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規則，預設：空
swagger.docket.<name>.name=參數名
swagger.docket.<name>.modelRef=指定參數類型
swagger.docket.<name>.parameterType=指定參數存放位置,可選header,query,path,body.form
swagger.docket.<name>.required=true=指定參數是否必傳，true,false
swagger.docket.<name>.globalOperationParameters[0].name=參數名
swagger.docket.<name>.globalOperationParameters[0].description=描述資訊
swagger.docket.<name>.globalOperationParameters[0].modelRef=指定參數存放位置,可選header,query,path,body.form
swagger.docket.<name>.globalOperationParameters[0].parameterType=指定參數是否必傳，true,false

說明：

<name>

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

分組配置示例

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

swagger.docket.aaa.globalOperationParameters[0].name

會覆寫同名的全局配置。

https://blog.didispace.com/swagger-starter-2-release/#JSR-303%E6%A0%A1%E9%AA%8C%E6%B3%A8%E8%A7%A3%E6%94%AF%E6%8C%81%EF%BC%881-5-0-%E6%94%AF%E6%8C%81%EF%BC%89 JSR-303校驗注解支援（1.5.0 + 支援）

支援對JSR-303校驗注解的展示，如下圖所示：

目前共支援以下幾個注解：

  • @NotNull

  • @Max、@Min

  • @Size

  • @Pattern

https://blog.didispace.com/swagger-starter-2-release/#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%85%A8%E5%B1%80%E5%93%8D%E5%BA%94%E6%B6%88%E6%81%AF%E9%85%8D%E7%BD%AE%EF%BC%881-6-0-%E6%94%AF%E6%8C%81%EF%BC%89 自定義全局響應消息配置（1.6.0 + 支援）

支援 POST,GET,PUT,PATCH,DELETE,HEAD,OPTIONS,TRACE 全局響應消息配置，配置如下

// 取消使用預設預定義的響應消息,并使用自定義響應消息
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

UI功能配置（1.6.0 + 支援）

  • 調試按鈕的控制(try it out) 
swagger.ui-config.submit-methods=get,delete

該參數值為提供調試按鈕的HTTP請求類型，多個用,分割。

如果不想開啟調試功能，隻需要如下設定即可：

swagger.ui-config.submit-methods=
  • 其他配置 
# json編輯器
swagger.ui-config.json-editor=false

# 顯示請求頭
swagger.ui-config.show-request-headers=true

# 頁面調試請求的逾時時間
swagger.ui-config.request-timeout=5000

ignoredParameterTypes配置（1.6.0 + 支援） 

# 基礎配置
swagger.ignored-parameter-types[0]=com.didispace.demo.User
swagger.ignored-parameter-types[1]=com.didispace.demo.Product

# 分組配置
swagger.docket.aaa.ignored-parameter-types[0]=com.didispace.demo.User
swagger.docket.aaa.ignored-parameter-types[1]=com.didispace.demo.Product

該參數作用：

Q. Infinite loop when springfox tries to determine schema for objects with nested/complex constraints?

A. If you have recursively defined objects, I would try and see if providing an alternate type might work or perhaps even ignoring the offending classes e.g. order using the docket. ignoredParameterTypes(Order.class). This is usually found in Hibernate domain objects that have bidirectional dependencies on other objects.

https://blog.didispace.com/swagger-starter-2-release/#Authorization-%E9%89%B4%E6%9D%83%E9%85%8D%E7%BD%AE-1-7-0-%E6%94%AF%E6%8C%81 Authorization 鑒權配置 (1.7.0 + 支援)

  • 新增 Authorization 配置項 
# 鑒權政策ID，對應 SecurityReferences ID
swagger.authorization.name=Authorization

# 鑒權政策，可選 ApiKey | BasicAuth | None，預設ApiKey
swagger.authorization.type=ApiKey

# 鑒權傳遞的Header參數
swagger.authorization.key-name=token

# 需要開啟鑒權URL的正則, 預設^.*$比對所有URL
swagger.authorization.auth-regex=^.*$

備注：目前支援

ApiKey

|

BasicAuth

鑒權模式，

None

除消鑒權模式，預設ApiKey，後續添加

Oauth2

支援

使用須知

  1. 預設已經在全局開啟了

    global

     的SecurityReferences，無需配置任何參數就可以使用；
  2. 全局鑒權的範圍在可以通過以上參數

    auth-regex

     進行正規表達式比對控制；
  3. 除了全局開啟外，還可以手動通過注解在RestController上進行定義鑒權，使用方式如下： 
// 其中的ID Authorization 即為配置項 swagger.authorization.name，詳細請關注後面的配置代碼
@ApiOperation(value = "Hello World", authorizations = {@Authorization(value = "Authorization")})
@RequestMapping(value = "/hello", method = RequestMethod.GET)
String hello();

關于如何配置實作鑒權，請關注以下code：

/**
 * 配置基于 ApiKey 的鑒權對象
 *
 * @return
 */
private ApiKey apiKey() {
    return new ApiKey(swaggerProperties().getAuthorization().getName(),
            swaggerProperties().getAuthorization().getKeyName(),
            ApiKeyVehicle.HEADER.getValue());
}

/**
 * 配置預設的全局鑒權政策的開關，以及通過正規表達式進行比對；預設 ^.*$ 比對所有URL
 * 其中 securityReferences 為配置啟用的鑒權政策
 *
 * @return
 */
private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.regex(swaggerProperties().getAuthorization().getAuthRegex()))
            .build();
}

/**
 * 配置預設的全局鑒權政策；其中傳回的 SecurityReference 中，reference 即為ApiKey對象裡面的name，保持一緻才能開啟全局鑒權
 *
 * @return
 */
private List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Collections.singletonList(SecurityReference.builder()
            .reference(swaggerProperties().getAuthorization().getName())
            .scopes(authorizationScopes).build());
}

最後，如果您正在學習Spring Boot，推薦一個連載多年還在繼續更新的免費教程：

《Spring Boot 2.x基礎教程》點選直達！

！如果學習過程中如遇困難？可以加入我們

Spring技術交流群

，參與交流與讨論，更好的學習與進步！

監控 前端開發 java 資料庫連接配接 api spring spring Java連接配接 學習swagger spring java開發 java資料前端 java資料spring
上一篇: 學會Python等于擁有整個世界！秒懂精通pip并快速體驗深度學習應用吧！【多圖建議收藏】下面給我們的手機安裝應用寶玩轉深度學習架構tensorflow
下一篇: Css盒子陰影及文本陰影效果總結

繼續閱讀