ApiBoot - ApiBoot Swagger 使用文檔

ApiBoot是一款基於SpringBoot1.x，2.x的接口服務集成基礎框架， 內部提供了框架的封裝集成、使用擴展、自動化完成配置，讓接口開發者能夠選着性完成開箱即用， 再也不爲搭建接口框架而犯愁，從而極大的提升開發效率。

ApiBoot經過整合Swagger2完成自動化接口文檔生成，只須要一個簡單的註解咱們就能夠實現文檔的開啓，並且文檔上面的全部元素均可以自定義配置，經過下面的介紹來詳細瞭解ApiBoot Swagger的簡易之處。

引入ApiBoot Swagger

在pom.xml配置文件內經過添加以下依賴進行集成：

<!--ApiBoot Swagger-->
<dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-swagger</artifactId>
</dependency>

注意： ApiBoot所提供的依賴都不須要添加版本號，可是須要添加版本依賴，具體查看 ApiBoot版本依賴

@EnableApiBootSwagger

在添加依賴後須要經過@EnableApiBootSwagger註解進行開啓ApiBoot Swagger相關的配置信息自動化構建，能夠配置在XxxApplication入口類上，也能夠是配置類，讓SpringBoot加載到便可。

相關配置

配置參數	參數介紹	默認值
api.boot.swagger.enable	是否啓用	true
api.boot.swagger.title	文檔標題	ApiBoot快速集成Swagger文檔
api.boot.swagger.description	文檔描述	ApiBoot經過自動化配置快速集成Swagger2文檔，僅需一個註解、一個依賴便可。
api.boot.swagger.base-package	文檔掃描的package	XxxApplication同級以及子級package
api.boot.swagger.version	文檔版本號	api.boot.version
api.boot.swagger.license	文檔版權	ApiBoot
api.boot.swagger.license-url	文檔版權地址	https://github.com/hengboy/ap...
api.boot.swagger.contact.name	文檔編寫人名稱	恆宇少年
api.boot.swagger.contact.website	文檔編寫人主頁	http://blog.yuqiyu.com
api.boot.swagger.contact.email	文檔編寫人郵箱地址	jnyuqy@gmail.com
api.boot.swagger.authorization.name	整合Oauth2後受權名稱	ApiBoot Security Oauth 認證頭信息
api.boot.swagger.authorization.key-name	整合Oauth2後受權Header內的key-name	Authorization
api.boot.swagger.authorization.auth-regex	整合Oauth2後受權表達式	^.*$

以上是目前版本的全部配置參數，大多數都存在默認值，可自行修改。

整合ApiBoot Security Oauth

若是你的項目添加了Oauth2資源保護，在Swagger界面上訪問接口時須要設置AccessToken到Header才能夠完成接口的訪問，ApiBoot Security Oauth默認開放Swagger全部相關路徑，若是項目內並不是經過ApiBoot Security Oauth2來作安全認證以及資源保護，須要自行開放Swagger相關路徑。

整合ApiBoot Security Oauth很簡單，訪問ApiBoot Security Oauth 查看。

攜帶Token訪問Api

啓動添加ApiBoot-Swagger依賴的項目後，訪問http://localhost:8080/swagger-ui.html頁面查看Swagger所生成的所有文檔，頁面右側能夠看到Authorize，點擊後打開配置AccessToken的界面，配置的AccessToken必須攜帶類型，如：Bearer 0798e1c7-64f4-4a2f-aad1-8c616c5aa85b。

注意：經過 ApiBoot Security Oauth所獲取的 AccessToken類型都爲 Bearer。

本章源碼地址：https://github.com/hengboy/api-boot/tree/master/api-boot-samples/api-boot-sample-swagger