Swagger實踐和總結

Swagger學習和實踐

 

最近安裝並使用了一下Swagger-ui、Swagger-editor和Swagger-codegen，感覺還不錯。

Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。Swagger的目標是對REST API定義一個標准的和語言無關的接口，可讓人和計算機無需訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過Swagger進行正確定義，用戶可以理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與為底層編程所實現的接口類似，Swagger消除了調用服務時可能會有的猜測。

Swagger是一組開源項目，其中主要要項目如下：

• Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。
• Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。
• Swagger-js: 用於JavaScript的Swagger實現。
• Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。
• Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger兼容API動態生成優雅文檔。
  
• Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。
  

  C:\tools\swagger-codegen>mvn package
  C:\tools\swagger-codegen\modules\swagger-codegen-cli>mvn package
  C:\tools\swagger-codegen\modules\swagger-generator>mvn package
  C:\tools\swagger-codegen>java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l spring-mvc -o yqu/petstore/spring-mvc
  C:\tools\swagger-codegen\yqu\petstore\spring-mvc>mvn package

  上述操作通過底層使用SpringFox庫，會創建帶有Swagger注釋的Spring MVC框架代碼，包括Controller和DTO類。這樣將Swagger-ui部署到Web應用內，就可以通過http://server:8002/v2/sdoc.jsp在線訪問API文檔了。
• Swagger-editor：可讓使用者在瀏覽器里以YAML格式編輯Swagger API規范並實時預覽文檔。可以生成有效的Swagger JSON描述，並用於所有Swagger工具（代碼生成、文檔等等）中。
  

 

除了Swagger項目自身支持的Java、Scala和JavaScript語言，Swagger社區中還提供了很多支持其他語言的第三方工具，覆蓋了Clojure、ColdFusion / CFML、Eiffel、Go、Groovy、.Net、Perl、PHP、Python、Ruby等各種編程語言。

 

Swagger總結

Swagger這類API文檔工具可以滿足下列需求：

• 支持API自動生成同步的在線文檔
  
  • 這些文檔可用於項目內部API審核
  • 方便測試人員了解API
  • 這些文檔可作為客戶產品文檔的一部分進行發布
• 支持API規范生成代碼，生成的客戶端和服務器端骨架代碼可以加速開發和測試速度

跟下列其他API文檔工具相比，Swagger各有優缺點，但它功能最多、也是最流行的。

• RESTful API Modeling Language (RAML)
• apiary的API Blueprint
• I/O Docs
• Web Application Description Language (WADL)