【Swagger】多是目前最好的 Spring Boot 集成 swagger 的方案

【Swagger】多是目前最好的Spring Boot集成 swagger 的方案


  聽說程序員最恨的兩件事：一件是別人不寫文檔，另外一件是本身寫文檔。

  可見文檔真的是程序員生活中相愛相殺的存在。一方面對於使用者來講，一份全面、準確的文檔簡直就是旅行時的地圖，烹飪時的菜譜，通關時的攻略。能夠極大的提升對接的效率與儘量的減小踩坑的機率。然而，一份全面而又準確的文檔談何容易。

  以接口文檔來講，程序員不想寫的緣由跟寫單元測試同樣，很大程序上在於它完徹底全是一個體力活，毫無創造性可言，枯燥而且乏味。更要緊的它不是一次性寫完就能夠了，還須要不停的維護，當你的業務變動進而致使代碼變更，使得請求值、響應值、接口名稱、字段註釋、校驗信息。。。。。均可能會修改。這個時候接口文檔就要同步更新。不然它就會變的不許確了。若是常常對接接口的同窗可能深有體會，這不光出現於公司內部，對接外部接口，或提供外部接口不時有這樣的問題。

  天下苦接口文檔久矣！忽然有一天，一個頭戴絲襪，氣宇軒昂的大俠出現，改變了這個局面。他經過一套自創的註解，就能夠自動生成一個在線的接口文檔，並且隨着代碼的變動，它也會跟着變化。極大的減小了人們的工做量。爲表達對於這位英雄的敬意，江湖人稱--絲襪哥(Swagger音譯)。

  一個典型的生成後 swagger 的接口文檔頁面如上圖所示。關於絲襪哥的傳奇故事，咱們今天就說到這裏。經過圖片其實能夠看出原生的界面、功能仍是比較有限的。首先沒有一個登陸界面，基本上在使用時沒幾我的改 swagger 的默認地址。因此別人發現你的接口地址很容易訪問到你的 swagger 頁面，這就帶來了安全風險。另外一點就是這個界面，怎麼說呢，至少不是我喜歡的款。仍是一點就是直接對接起 Spring Boot 仍是有點麻煩的，各類 bean 要手動配置，一點也不 Spring Boot。

  凡此種種，終於有一天。在 github 閒逛時，發現了一個不錯的 swagger 的工具包，一用就愛不釋手。項目地址下面就演示一下如何使用。

引入依賴

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.1.5-RELEASE</version>
</dependency>

  2.1.5-RELEASE是當前的最新版，後續版本你們能夠在項目地址上去看。

配置篇

spring:
  swagger:
    enabled: true

  配置結束了，若是你只想用最基本的 swagger 的功能的話。訪問http://{host:port}/swagger-ui.html後會有以下界面

  該項目的 UI 是使用 Vue 重寫的較原版不管是顏值仍是功能都有很大的提高。好比添加了搜索、接口統計等不少實用功能。若是咱們想開啓登陸驗證，防止接口文檔被外部人員訪問到，只要添加三條配置就能夠了。

spring:
  swagger:
    enabled: true
    security:
      filter-plugin: true
      username: kiwi
      password: 123456

  咱們再次訪問接口頁面，界面被攔截了，變成了以下登陸界面。

  輸入配置的帳號與密碼，又見到了熟悉的接口頁面了。

尾聲

  是否是感受很方便，很 easy。其實還有不少功能，由於篇幅有限，更重要是做者自己已經寫了很好的使用文檔，沒有必要在本文再一一列舉出來（好吧，實際上是我懶），你們能夠到項目頁面接着學習。另外在做者的頁面能夠看到他本人的博客地址，是一個寶藏博主哦！

關注公衆號「KIWI的碎碎念」，分享的不只僅是技術