Swagger 2（Open API v3.0） Java 文件生成指南（上）
介面文件生成器指的是寫好了 API 介面 之後，讓前臺開放人員（包括不限於 H5 前端、iOS/Android 客戶端、小程式等）呼叫介面時的文件。個人比較主張“程式碼即文件”，即文件編寫在原始碼之中。
先全網選型了一下，發現適合 Java 的有下面幾種開源的方案。
- Swagger，也就是本文的主角，實際情形比較複雜，下面再說
- apidoc.js，node.js 方案，通過註釋寫文件，而不是真正程式碼，捨棄之
- RAP，淘寶出品，沒深入瞭解
- Api2Doc2，國人出品，for Java 的，勵志做 Java 屆最好用的文件工具，不過聽過生成的文件還要 SpringBoot 來跑，太重了，捨棄之。
看來也只是 Swagger 比較合適。然而 Swagger 這貨也不簡單。首先是搞 Java 言必稱 Spring，所以文件工具也首推 for Spring 的（很文章介紹 Swagger 的一個外掛，實際 Swagger 真身是 Swagger Core）。我不是搞 Spring 的就不能用 Swagger 呢？肯定不是， Swagger 不是 Spring 專屬的，只不過 Spring 一家獨大，所以網上資料也淨是它的，連牆外的 google 也是……
刨英文吧，官方的文件是唯一的指南了……
第二個問題，Swagger 本身的問題，這貨通過註解實現文件，舊版的是自己的註解，但後來呢，成立的一個什麼 Open API 組織還是什麼標準，針對文件服務提出新的開放規範。好吧～舊的註解通通要變身了，所以呢，現在很多文章的停留在舊版的註解上。新版的還是要看官方文件。
那咱就用新版吧～
可是怎麼用呢？Swagger 這貨介紹新版文章幾乎為 0，官文又寫得雲裡霧裡，我悲苦逼吶～說要 jetty 伺服器，然後我的 maven 下載 jar 又檔案損壞，搞一大輪，發現 tomcat 7 不行要 tomcat 8，shit 幾乎快放棄。
抱著這種想法，通常是柳暗花明又一炮的時候，——我發現它的 simple 專案，都齊備著呢，不同開源專案都有，我想要的是最普通的 Servlet 那個，也有，於是 checkout 下來跑一下，齊活了。
使用說明
首先，Swagger 是這樣子的：
- 通過註解編寫文件，這很科學，沒毛病
- 除了自己的註解，還能辨識來自 javax.ws.rs 即 JAX-RS（Java API for RESTful Web Services） 的註解。如果你的介面專案是用 JAX-RS，那就完美了；如果你不知道這是啥，還是先百度下。反正就是 Java 的一個標準，我們用的是它註解。
- 官文說要 Jetty 但 tomcat 也行，不過因為一個 jar 包版本問題，得 Tomcat 8 才行
- 實際引用的是 Swagger Core，for 普通 Java 專案的。如果你用 Spring Boot 這裡跑錯片場了。
- Swagger Core 能解析程式碼的文件部分，形成 YAML、JSON 定義檔案，這是給機器看不是人看的。不能直接渲染最終的 HTML/Markdown，要渲染出漂亮的文件， 那是 Swagger UI 乾的事情。所以得先匯出定義檔案再弄文件頁面。
- Swagger為我們提供了另外一種比較優雅的方式：就是你先訂立介面，然後再去生成介面；也就是使用介面文件去生成程式碼，對此我保留意見，但用於程式碼生成器還是不錯的
其次，是一些相關有用的網址：
普通 Servlet 樣例
官方樣例的“純度”不是很夠，參雜其他多餘的依賴，於是我做了一個普通 Java Web 專案來跑，清爽。
1、新建 Web 專案並將其轉為 Maven 專案，新增下面依賴。
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2</artifactId>
<scope>compile</scope>
<version>2.0.4</version>
</dependency>
<!-- 做 RESTful 介面的註解 -->
<dependency>
<groupId>javax.ws.rs</groupId>
<artifactId>javax.ws.rs-api</artifactId>
<version>2.1</version>
</dependency>
2、修改 web.xml，增加一個 servlet，訪問生成的文件定義檔案。
<servlet>
<!-- 生成介面文件服務 -->
<servlet-name>OpenApi</servlet-name>
<servlet-class>io.swagger.v3.jaxrs2.integration.OpenApiServlet</servlet-class>
<init-param>
<param-name>openApi.configuration.resourcePackages</param-name>
<param-value>io.swagger.sample.resource</param-value><!-- 指定掃描的包 -->
</init-param>
<!-- 另外可以在 classpath 中引入配置檔案 openapi-configuration.json or openapi-configuration.yaml -->
<!-- 還可以在下面配置中指明配置檔案的位置 -->
<!-- <init-param> <param-name>openApi.configuration.location</param-name>
<param-value>/openapi-configuration.json</param-value> </init-param> -->
<load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>OpenApi</servlet-name>
<url-pattern>/openapi/*</url-pattern>
</servlet-mapping>
3、寫一個測試，在 java 中新增 Swagger 註解，寫上你的文件，
註解很多的，看你怎麼寫文件。
4、執行起來，就是 Run Server，Swagger 會在 Tomcat 啟動時解析文件。啟動後，訪問 Servlet，如 http://localhost:8080/test_doc/openapi/openapi.json，如無意外會是：
好了，這就得到文件的定義檔案。
接著就是生成漂亮的 html，可俺還不會，沒研究出來 Swagger-UI～唉.
另外可以在 Swagger Editor http://editor.swagger.io/ 中預覽下，就是把定義檔案的內容貼上到 editor 裡面去。