上一篇我們用 Flask-RESTX 建立了第一個簡單的 API。
app.py

from flask import Flask
from flask_restx import Api, Resource

app = Flask(__name__)
api = Api(app)

@api.route('/tasks')
class Tasks(Resource):
    def get(self):
        return {
            "name": "Flask",
            "completed": False
        }

if __name__ == '__main__':
    app.run(debug=True)
    

我們設定了 /tasks 這個 Path，並使用 get() 來處理 GET Request。

上一篇如果要測試這個 API，我們是直接在瀏覽器打開：

http://127.0.0.1:5000/tasks

就可以看到 API 回傳的資料。

{
  "name": "Flask",
  "completed": false
}

但是如果之後建立的 API 越來越多，可能會有不同的 Path，也會有 GET、POST、PUT、DELETE 等不同的 HTTP Method。

如果每一個都要自己記，就會變得比較麻煩。

這時候就可以使用 Swagger。

Swagger 是什麼？

Swagger 可以先簡單理解成：

一個可以查看 API 資訊，還有可以直接測試 API 的介面。

我們可以透過 Swagger 看到目前有哪些 API、使用什麼 Path，以及可以使用哪些 HTTP Method。

這裡順便講一下名字，因為查資料的時候很容易混在一起：

OpenAPI 是這份「API 規格」的正式名稱（以前叫 Swagger 規格）
Swagger UI 則是把規格畫成網頁、可以點來點去的那個介面

我們平常說的「打開 Swagger」，講的通常就是 Swagger UI。

而 Flask-RESTX 本身就可以幫我們產生這份文件。

為什麼不用自己做？

上一篇我們寫了：

api = Api(app)

我們把 Flask app 傳給 Api，建立一個和 Flask app 連接的 Api 物件。

使用 Flask-RESTX 的 Api 後，它也會幫我們產生 Swagger UI。

所以我們不需要自己另外建立 Swagger 頁面。

想要打開 Swagger

我們先啟動上一篇的程式：

python app.py

前面我們都是打開：

http://127.0.0.1:5000/tasks

來直接測試 /tasks。

這次我們直接打開：

http://127.0.0.1:5000/

就可以看到 Flask-RESTX 產生的 Swagger UI。

打開 http://127.0.0.1:5000/ 看到的 Swagger 首頁

（如果這裡看到的是 Hi Flask! 而不是 Swagger，就是 Day 11 提醒的那個問題，表示 / 還被舊的 @app.route(‘/’) 佔著，把它拿掉就可以了。）

打開後，可以看到：

GET /tasks

為什麼 Swagger 會知道我們有這個 API？

因為上一篇的程式中有：

@api.route('/tasks')
class Tasks(Resource):
    def get(self):
        return {
            "name": "Flask",
            "completed": False
        }

@api.route(‘/tasks’) 設定了 /tasks 這個 Path。

而：

def get(self):

是用來處理 GET Request。

所以 Swagger 就可以把這個 API 顯示成：

GET /tasks

也就是說，我們並沒有另外寫文件，
Flask-RESTX 是直接從我們的程式「看出」有哪些 API，再把它畫成畫面。

這也是為什麼它可以一直跟程式保持一致，不會像手寫文件那樣改完程式忘記改文件。

用 Swagger 測試 API

接下來就實際用 Swagger 測試看看。

點開 GET /tasks 並按下 Try it out 的畫面

按下 Execute 後，Swagger 就會對 /tasks 發出 GET Request。

在畫面中的 Request URL 可以看到：

http://127.0.0.1:5000/tasks

所以原本是我們自己在瀏覽器輸入 /tasks 來發出 GET Request。

現在則是透過 Swagger 幫我們發出 Request。

Request 到達 /tasks 後，因為這次是 GET Request，所以會執行：

def get(self):
    return {
        "name": "Flask",
        "completed": False
    }

最後 Swagger 就會顯示 API 回傳的 Response：

{
  "name": "Flask",
  "completed": false
}

按下 Execute 後，看到 Response Code 200 和回傳的 JSON：

整個流程可以看成：

Swagger 按下 Execute
      ↓
發出 GET Request 到 /tasks
      ↓
Flask-RESTX 找到 /tasks
      ↓
因為是 GET Request
      ↓
執行 get()
      ↓
回傳資料
      ↓
Swagger 顯示 Response

所以 Swagger 並不是取代我們原本的 API，而是提供一個介面，讓我們可以更方便地查看和測試 API。

Swagger UI 是怎麼畫出來的？

如果想看得更清楚一點，可以打開：

http://127.0.0.1:5000/swagger.json

會看到一大包 JSON。

swagger.json 的內容

這份就是剛剛說的 OpenAPI 規格。

Flask-RESTX 會先從我們的程式產生這份 JSON，
Swagger UI 再讀這份 JSON，把它畫成我們看到的那個畫面。

所以畫面上會出現什麼，其實都是從程式來的。

順便讓文件好看一點

現在 Swagger 首頁上的標題是預設的，可以自己改：

api = Api(
    app,
    title='Task API',
    version='1.0',
)

重新啟動之後，Swagger 上方就會顯示我們自己的標題和版本。

改完 title 和 version 之後的 Swagger 首頁

另外，如果不想讓 Swagger 佔用 / 這個路徑，也可以自己指定：

api = Api(app, doc='/docs')

這樣文件就會變成在 http://127.0.0.1:5000/docs，
/ 就可以留給別的用途。

還有一個很方便的地方，是之後會一直用到的：

Flask-RESTX 會把 method 的 docstring 當成 Swagger 上的說明。

也就是只要寫：

def get(self):
    """取得所有作業"""
    ...

Swagger 上的 GET /tasks 旁邊就會出現「取得所有作業」。

之後 API 變多的時候，這個會讓文件清楚很多。

今天我們認識了 Swagger，也實際透過 Swagger 測試了上一篇建立的 GET /tasks。

不過目前我們測試的 GET Request 主要是在取得資料。

如果今天要使用 POST 新增一筆資料，就需要把要新增的資料一起傳給後端。

那 API 要怎麼取得 Request 傳進來的資料呢？

下一篇就來看看 Request Body 和 api.payload。