API文檔工具Swagger
簡介
問題：在我們API開發中，服務端和客戶端會約定介面文檔，而在實際開發中則可能出現，介面文檔延遲更新，造成客戶端看到的介面和服務端實際開發的介面不一致的問題；
Swagger 文檔提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 介面名、介面參數 等 API 信息。
你可以通過一個文本編輯器來編輯 Swagger 文件，或者你也可以從你的代碼註釋中自動生成。各種工具都可以使用 Swagger 文件來生成互動的 API 文檔。
swagger的一些常用工具
1. swagger文件編寫工具 (swagger editor)：在線版本的swagger編輯器：http://editor.swagger.io/，支持json，yaml兩種格式
Advertisements
如果想了解swagger文檔的編寫語法，可以在http://swagger.io/docs/specification/swagger-extensions/這裡查看
2. swagger ui可視化文件生成工具 (swagger ui)：靜態頁面（用於將json，yaml轉化為可視化的頁面顯示）
3. Swagger-codegen (swagger codegen)：用於生成客戶端和服務端各個語言的代碼
4. swagger hub介面管理 (swagger hub) ：swagger文檔雲端管理工具，類似於github
swagger api 集成
目前官網上有提供 Jersey 1.X Jersey 2.X RESTEasy 2.X Mule的配置方法，官網wiki寫的很詳細https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X#hooking-up-swagger-core-in-your-application
Advertisements
對於各個不同的rest服務，git-hub也有提供相關的demo，https://github.com/swagger-api/swagger-samples
配置樣例（jersey2）
配置API項目過程中的樣例，主要有兩種配置方式：web.xml的servlet配置、BeanConfig配置。
1. 引入swagger相關jar包
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey2-jaxrs</artifactId>
<version>1.5.10</version>
</dependency>
2. web.xml中jersey配置中加入對，swagger相關resource的路徑
<servlet>
<servlet-name>JerseyServlet</servlet-name>
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>jersey.config.server.provider.packages</param-name>
<param-value>
io.swagger.jaxrs.listing,<!--swagger相關資源-->
com.sohu.tv.api4.rest.controller <!--業務資源>
</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>JerseyServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
3. swagger相關配置（一些全局描述）
web.xml中servlet配置（第一種方式）
<servlet>
<servlet-name>Jersey2Config</servlet-name>
<servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
<init-param>
<param-name>api.version</param-name>
<param-value>1.0.0</param-value>
</init-param>
<init-param>
<param-name>swagger.api.basepath</param-name>
<param-value>/</param-value>
</init-param>
<init-param>
<!-- 是否掃描全部資源，包含沒使用swagger註解聲明過的rest資源 -->
<param-name>scan.all.resources</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
此外還有：
swagger.api.host 、 swagger.api.schemes、swagger.api.title、
swagger.filter都可以在servlet的參數中聲明
BeanConfig配置（第二種方式）
<!–web.xml中聲自定義明配置的servlet-->
<servlet>
<servlet-name>Bootstrap</servlet-name>
<servlet-class>com.sohu.tv.api4.utils.Bootstrap</servlet-class>
<init-param>
<param-name>scan.all.resources</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
// 自定義servlet的類配置
public class Bootstrap extends HttpServlet {
@Override
public void init(ServletConfig config) throws ServletException {
super.init(config);
BeanConfig beanConfig = new BeanConfig();
beanConfig.setVersion("1.0.2");
beanConfig.setSchemes(new String[]{"http"});
beanConfig.setHost("localhost:8002");
beanConfig.setBasePath("/api");
// resourcepackage指明需要掃描的業務rest資源路徑（未指明，則不會掃描資源）
beanConfig.setResourcePackage("io.swagger.resources");
// setScan說明beanconfig是否生效被掃描
beanConfig.setScan(true);
// 如果想讓未加swagger註解的rest資源被掃到，需加如下配置：
ReaderConfigUtils.initReaderConfig(config);
}
}
完成上述配置，既可以在項目中，使用swagger註解完成介面描述。