# Swagger

+ `API` 文件規格
+ 制定前後端 `Web API` 的通訊規範

## Context

+ 多人協作同時開發

## Problem

+ 清楚完整的 API 文件對於前後端分離專案至關重要
+ API first
+ 當需求變更，需要修改API規格時，若是使用 `word`, `excel` 等方法紀錄 `API` 規格，可能會發生文件更新不即時，造成實際的 `API` 與技術文件上的規範不一致。

## Solution

+ 基於程式碼中的註解，動態的產出文件。
+ 幫助構建、設計和紀錄 `RESTFul API`。
+ SwaggerUI: 讀取註解訊息，將 `Open API` 規格以可視化互動式UI的方式呈現。

## Open API

+ Open API **規範**(Open API Specification)以前稱為 `Swagger API` 規範，是 `RESTFul API` 的 API 規格描述。
+ URL
+ `Action` 的參數與返回值
+ 身分認證/權限驗證
+ Method
+ GET
+ POST
+ PUT
+ DELETE
+ 使用 `YAML` 或 `JSON` 格式進行撰寫
+ 使用 [線上編輯](https://editor.swagger.io/)