推薦一款接口 API 設計神器!
今天棧長給大家推薦一款接口 API 設計神器,傳說中的,牛逼哄洪的 Swagger,它到底是什麽?今天為大家揭開謎底!
Swagger是什麽?
官網:https://swagger.io/
Swagger 如官網所示,它是最好的 API 構建工具。
它是一個圍繞 OpenAPI 規範構建的開源工具,它可以幫助我們設計、構建、記錄和使用 REST API 接口。
Swagger 包含的主要套件:
- Swagger Editor - 基於瀏覽器的編輯器,用來編寫 OpenAPI 規範。
- Swagger UI - 基於 OpenAPI 規範動態生成 API 規範文檔。
- Swagger Codegen - 個模板驅動引擎,用來生成客戶端代碼。
圖片來源見博客水印。
OpenAPI是什麽?
上面有說到 Swagger 是一個圍繞 OpenAPI 規範構建的開源工具,那麽 OpenAPI 是什麽呢?
OpenAPI 規範,以前叫 Swagger 規範。它是一個為 REST APIs的接口定義的規範。OpenAPI 可以定義的 API 實體內容包括以下幾個部分。
- 請求地址(如:/user)
- 請求類型(如:GET、POST 等)
- 請求參數
- 響應參數
- 驗證方式
- 文檔信息:如聯系人、許可證、服務條件等
這個 OpenAPI 規範可以用 YAML 或者 JSON 來編寫,這種格式非常易於學習,可讀性對開發人員非常友好。
完整的 OpenAPI 規範可以去官網看一下。
https://github.com/OAI/OpenAPI-Specification
編寫文檔地址:
http://editor.swagger.io/
為什麽需要Swagger?
現在的互聯網架構都是前後端分離的模式,還有現在是移動互聯網時代了,APP 需要與後端服務器通信也需要維護一套接口,API文檔自然就成了前後端開發人員聯系的紐帶。
編寫 API 文檔的方式也各有不同,有用 WORD 編寫的,有用 confluence 等編寫的,但這些方式都不能動態更新,每次接口變更都需要手動維護文檔,甚是麻煩。有了 Swagger,可以先做完接口,通過 Swagger 來動態生成和更新 API 文檔。
後面的文章會繼續介紹如何使用 Swagger 註解來自動生成 API 文檔,及如何集成 Spring Boot 來應用實戰,關註Java技術棧微信公眾號,在後臺回復關鍵字 "工具" 可獲取所有歷史 Java 工具類文章教程及更新。
本文原創首發於微信公眾號:Java技術棧(id:javastack),關註公眾號在後臺回復 "工具" 可獲取更多,轉載請原樣保留本信息。
推薦一款接口 API 設計神器!