作者：**HelloGitHub-[追夢人物](https://www.zmrenwu.com)** 大多數情況下，開發的介面都不是給開發這個介面的人用的，所以如果沒有介面文件，別人就無法有哪些介面可以呼叫，即使知道了介面的 URL，也很難知道介面需要哪些引數，即使知道了這些引數，也可能無法理解這些引數的含義。因此介面文件應該是專案必不可少的配置。 編寫介面文件有很多種方式，最為簡單直接的方式就是開啟一個記事本或者 word 文件，將介面的詳細資訊和用法寫下來，別人就可以參考這個文件來呼叫介面。這樣做雖然簡單，但弊端也很明顯：一是需要寫大量的描述文字，非常枯燥，但其實這些資訊在程式碼中已有體現，有點像是使用自然語言又把程式碼寫了一遍；二是一旦介面有了更新，就必須手動同步更新介面文件，開發人員很容易搞忘這件事，導致介面文件的內容和介面的實際功能不一致。 因為很多介面的資訊其實在程式碼中已有體現，人們自然而然就想到能否直接從寫好的程式碼中自動提取相關資訊來生成文件，這樣改了程式碼，介面文件也會自動更新，上面說的兩個問題就都可以解決了。 當然寫介面文件不是搞文學創作，為了直接從寫好的程式碼中自動提取資訊來生成文件，就必須要有一套標準的文件格式，否則工具無法知道要從程式碼中提取出哪些資訊，資訊提取之後，也不知道該如何組織這些資訊。 經過大家的努力，現在已經有了很多成熟的介面文件標準和生成工具，其中 [OpenAPI Specification](https://swagger.io/specification/) 就是一個被廣泛接收和使用的標準，我們部落格介面使用的文件自動化工具，也會基於 OpenAPI 標準從程式碼中提取文件資訊，然後組織為 OpenAPI 的標準格式。 **小貼士：** 大家更為熟悉的，和 OpenAPI 相關的一個名詞是 swagger。[Swagger](https://swagger.io/) 提供一系列免費開源的 OpenAPI 相關的工具，他們背後的公司是 [SMARTBEAR](https://smartbear.com/)，號稱 code quality tools 開發行業的領導者。 ## OpenAPI 介紹 介面文件不是文學作品，它所需要的內容基本都是固定的。例如對一個 RESTful 風格的介面來說，只需要知道以下這些關鍵的資訊就足夠完成對它的呼叫了。反過來，這些資訊也就可以定義一個完整的 RESTful 風格的介面： - 請求的 HTTP 方法和 URL。 - 接收的引數（包括 URL 中的路徑引數、查詢引數；HTTP 請求頭的引數；HTTP 請求體等引數）。 - 介面返回的內容。 OpenAPI 對以上資訊進行了標準化，從而提出了 [OpenAPI specification](https://swagger.io/specification/)，只要文件內容符合這個標準，OpenAPI 工具就可以對它進行處理，例如視覺化文件工具就可以讀取文件內容生成 HTML 格式的文件。 **注意：** OpenAPI specification 目前最新版本是 3，但目前大部分工具對 2 的支援最好，教程中使用的庫僅支援 2。 ## drf-yasg [drf-yasg](https://github.com/axnsan12/drf-yasg) 是一個 django 的第三方應用，它可以從 django-rest-framework 框架編寫的程式碼中自動提取介面資訊來生成符合 OpenAPI 標準的文件。我們將使用它來生成部落格應用的介面文件。 第一步當然是安裝 drf-yasg，進入專案根目錄，執行命令 ： ### Command Tab ```bash Linux/macOS $ pipenv install drf-yasg ``` ```shell Windows ...\> pipenv install drf-yasg ``` 然後將 drf-yasg 新增到 `INSTALLED_APPS` 配置項中： ```python # filename="blogproject/settings/common.py" INSTALLED_APPS = [ # 其它已新增的應用... "pure_pagination", # 分頁 "haystack", # 搜尋 "drf_yasg", # 文件 ] ``` 接著使用 drf_yasg 提供的函式來建立一個 django 檢視，這個檢視將返回 HTML 格式的文件內容，這樣我們就可以直接在瀏覽器檢視到部落格的介面文件： ```python # filename="blogproject/urls.py" from django.urls import include, path, re_path from drf_yasg import openapi from drf_yasg.views import get_schema_view from rest_framework import permissions, routers schema_view = get_schema_view( openapi.Info( title="HelloDjango REST framework tutorial API", default_version="v1", description="HelloDjango REST framework tutorial AP", terms_of_service="", contact=openapi.Contact(email="[email protected]"), license=openapi.License(name="GPLv3 License"), ), public=True, permission_classes=(permissions.AllowAny,), ) urlpatterns = [ # 其它已註冊的 URL 模式... # 文件 re_path( r"sw