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)