Swagger實踐和總結

Swagger學習和實踐

 

最近安裝並使用了一下Swagger-uiSwagger-editorSwagger-codegen,感受還不錯。html

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

Swagger是一組開源項目,其中主要要項目以下:node

  • 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實踐和總結
  • 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實踐和總結

 

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

 

Swagger總結


Swagger這類API文檔工具能夠知足下列需求:github

  • 支持API自動生成同步的在線文檔
    • 這些文檔可用於項目內部API審覈
    • 方便測試人員瞭解API
    • 這些文檔可做爲客戶產品文檔的一部分進行發佈
  • 支持API規範生成代碼,生成的客戶端和服務器端骨架代碼能夠加速開發和測試速度


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

相關文章
相關標籤/搜索