**一、前言
前六天從API的基本概念開始，
一步一步認識了HTTP、Request、Response、GET、POST、URL、Endpoint、Parameters、JSON，以及HTTP Status Code。
雖然已經知道API大概是怎麼運作的，
但如果今天真的要使用一個API還是會遇到一個問題
要怎麼知道這個API可以怎麼使用？
例如 ：
API有哪些Endpoint？
要使用GET還是POST？
可以傳入哪些Parameters？
回傳的資料又是什麼？
這時候就需要API文件，
而Swagger就是常見的API文件與測試工具之一。
⸻
**二、Swagger是什麼？
Swagger是一套用來描述、建立與測試API的工具，
簡單來說可以把它想成
API的使用說明書＋可以直接操作的測試介面。
如果API沒有文件，
我們可能只拿到一個網址卻不知道這個網址到底要怎麼使用，
而Swagger會把API提供的功能整理出來
例如：
GET /books
POST /books
GET /books/{id}
也可以看到每個Endpoint可以使用哪些參數以及可能回傳什麼資料。
對剛開始學API的人來說，
Swagger可以幫助我們更容易理解API的結構。
⸻
**三、Swagger UI是什麼？
我們在網路上看到的Swagger，
很多時候其實是Swagger UI。
Swagger UI會把API文件以網頁介面的方式呈現。
通常可以看到不同的 Endpoint
例如：
GET
/books
POST
/books
點開之後還可以看到：
有些Swagger UI還會提供Try it out按鈕，
讓使用者直接在網頁上輸入參數並送出Request，
這就代表我們不需要自己寫程式也可以直接測試API。
⸻
**四、實際操作Swagger
今天的實作就是找一個有Swagger UI的公開API並實際操作一次。
操作步驟：
操作後通常可以看到類似：
Request URL→Response Code 200→Response Body→JSON 資料
這時候就可以把前六天學到的內容全部串起來
例如：
Swagger→選擇 GET Endpoint→輸入 Parameters→送出 Request→Server→Status Code
→JSON Response
⸻
**五、Swagger和直接輸入API網址有什麼不同？
前幾天在瀏覽器輸入API URL就可以直接取得資料，
那為什麼還需要Swagger？
最大的差別就是：
直接輸入API網址，
比較像是在使用API，
Swagger則可以讓我們先了解API怎麼使用再進行測試。
例如直接看到：
https://example.com/books
我們可能不知道它有哪些功能，
但在Swagger裡
可以看到：
GET /books
GET /books/{id}
POST /books
DELETE /books/{id}
就能更清楚知道這個API提供哪些操作。
所以Swagger對API的學習和測試都很有幫助。
⸻
**六、第一週實作整理
經過這七天的學習，
開始可以把一個API Request從頭到尾串起來，
例如今天透過Swagger測試一個GET API：
選擇 Endpoint
↓
設定 Parameters
↓
送出 GET Request
↓
API Server
↓
取得 Status Code
↓
收到 JSON Response
這其實就是前幾天學到的內容，
只是今天第一次把它們實際放在一起操作。
透過Swagger，也可以更清楚地看到API文件和實際API操作之間的關係。
⸻
**七、總結
今天認識了Swagger和Swagger UI，
了解到他可以用來查看API文件、了解 Endpoint與Parameters，
也可以直接測試API。
實際操作後，
我也發現Swagger可以讓API的使用方式變得比較直觀，
不需要一開始就自己寫程式。
到這裡第一週主要是在建立Web API的基礎概念。
從最開始的：
API 是什麼？
一路學到：
HTTP → Request / Response → GET / POST → URL / Endpoint / Parameters → JSON → Status Code → Swagger
接下來就不會只停留在API的基本概念，
而是要開始實際使用不同類型的公開API。
第二週會先從書籍API開始，
實際查詢書籍資料並觀察不同Parameters如何影響API回傳的結果。
iThome鐵人賽
看影片追技術