Last Updated on 2023-07-18 by Clay
介紹
在 FastAPI 官方文件中，有一段關於『自動生成交互式文件』的說明：
- Robust: Get production-ready code. With automatic interactive documentation.
如果要使用這個功能，我們可以在開啟 FastAPI 的服務後輕鬆調用 $URL/docs —— 但問題是如果今天我們文件的應用場景不是給自己看、而是必須交付給客戶呢？
實際上，FastAPI 並不支援靜態文件的生成，如 html、PDF 或像 Sphinx。我們需要另外處理才行。然而，由於 FastAPI 的文件是基於標準 OpenAPI 的格式，所以我們還是可以利用其他工具來生成靜態文件。
內建交互式文件
由於服務和功能都是我們自己寫的，所以我們一定很清楚開啟服務的位置。輸出 $URL/docs，你可以看見以下畫面：
可以看到我有數個功能，一個 POST 和兩個 GET。但是這可能不是交付給客戶最好的文件類型（而且也非靜態）。
ReDoc
如果我們希望看另外一種風格的文件，我們可以把開啟的文件路徑更改為 $URL/redoc，我們就能看到另外一種不同風格的文件。
也正是這種格式，我們可以將其使用 redoc-cli 等工具將其轉換成靜態文件。
輸出靜態文件
首先，你會需要使用 npm 進行 redoc-cli 工具的安裝。
npm i -g @redocly/cli@latest
接著，我們需要把 FastAPI 自動生成的 openapi.json 文件下載到本地端。接著就是使用 redoc-cli 工具將其重新解析為 html 格式的檔案，接著直接打開檔案（預設名稱為 redoc-static.html）就會看到靜態文件了！
wget $URL/openapi.json
npx @redocly/cli bundle openapi.json
open redoc-static.html
Output:
雖然跟上面的文件長得一樣，但這可是存在於本地端且可隨時打開的！
以上，就是從 FastAPI 生成靜態文件的方法紀錄。