Skip to content

Latest commit

 

History

History
91 lines (60 loc) · 7.71 KB

swagger.md

File metadata and controls

91 lines (60 loc) · 7.71 KB

Swagger

  • Swagger 唸做 [‵swæɡɚ]，意思是 "昂首闊步"。
  • 做為 OpenAPI Specification (OAS，舊稱 Swagger Specification) 的 API tooling，照顧到了整個 API development/delivery lifecycle - design (Swagger Editor)、build (Swagger Codegen)、documentation (Swagger UI)、test 與 deployment。
  • 背後是 SmartBear，自稱最懂 API，因為 SoapUI 也是產品之一。

參考資料：

OpenAPI Specification (OAS)

  • OpenAPI Specification (OAS) 是一種描述 RESTful API 的格式 (舊稱 Swagger Specification)，也就是 RESTful contract for your API；包括 endpoints、operations、input parameters、output、authentication 等。
  • OpenAPI file 可以用 JSON 或 YAML 寫，跟程式語言無關 (language-agnostic)，強調 human & machine readable。

參考資料：

  • World's Most Popular API Framework | Swagger 一開始就提到 "framework of API developer tools for the OpenAPI Specification (OAS)"，之前叫做 Swagger Specification。所謂 specification 就是 "RESTful contract for your API"，用 human & machine-readable format 描述 resources & operations。另外在 Tried & Trusted 提到 "accepted standard for describing RESTful APIs" 且大量被採用。
  • About Swagger Specification | Documentation | Swagger 一種 API description format，可以用 JSON 或 YAML 寫。一個 OpenAPI file 用來描述整個 API，包括 endpoints (例如 /users)、operations (例如 GET /users、POST /users)、就 operation 有哪些 input parameters 及 output、驗證的方式 (authentication)、聯絡方式、授權等。
  • OpenAPI Specification - Wikipedia 做為 interface file 的 specification #ril
  • OpenAPI Specification | Swagger 文件好長，像是參考手冊 #ril

OpenAPI Specification 與 RAML、API Blueprint?

  • 2015 年 SmartBear 藉 Linux Foundation 的贊助創了一個 Open API Initiative (OAI)，並把 Swagger Specification 捐給該組織，當時 RAML 與 API Blueprint 也在考慮之列。
  • 或許是因為 Swagger 在 API tooling 這一塊持續耕耕，Swagger Specification 在 2016 更名為 OpenAPI Specification，之後 2017 RAML (RESTful API Modeling Language) 的主要開發商 MuleSoft 也加入 OAI 並開源自己的工具，可以從 RAML 轉出 OAS。整個局勢看來已是 OAS 的天下。

參考資料：

  • OpenAPI Specification - Wikipedia 2015 SmartBear 藉由 Linux Foundation 的贊助起了一個 Open API Initiative (OAI) 的組織，並把 Swagger Specification 捐給該組織 (當時 RAML 與 API Blueprint 也在考慮之列)，2016 更名為 OpenAPI Specification，2017 RAML (RESTful API Modeling Language) 的主要開發商 MuleSoft 也加入 OAI 並開源自己的工具，可以從 RAML 轉出 OAS。
  • Current Members - Open API Initiative OAI 的成員很嚇人，有 IBM、Google、Adobe、Microsoft、Atlassian、SAP、Salesforce 等。

新手上路 {: #getting-started }

  • 先把 OpenAPI Specification (OAS) 與 Swagger 的關係搞懂。
  • 知道 Swagger Editor、Codegen、UI 各自的用途 - 對應到 API development lifecycle 的哪個階段。

參考資料：

Swagger Editor、Codegen、UI、SwaggerHub?

Swagger UI {: #ui}

跟 Test 的關係??

跟 Deployment 的關係??

  • World's Most Popular API Framework | Swagger 提到 "enabling development across the entire API lifecycle, from design and documentation, to test and deployment"
  • Deploy Your API 提到 AWS API Gateway #ril
  • AWS API Gateway Console 的 Get Started 按下去，提示 "Welcome to Amazon API Gateway. To create your first API, we have pre-populated the import form with a Pet Store API defined using Swagger 2.0. To get started, close this modal and select Import in the Create API form."

參考資料 {: #reference }

社群：

更多：

手冊：