Django ，作為 Python 編寫的一個優秀的開源 Web 應用框架，特別適用於快速開發的團隊。對於很多場景來説，我們需要一份 API 文檔，好處實在太多了：
- 提高開發效率：開發者可以基於 API 文檔 快速學習和嘗試 API，同時 Swagger 文件也可以在許多不同的平台上從代碼註釋中自動生成，減少了手動編寫文檔的時間和精力。
- 方便接口測試：基於 API 文檔可以生成客户端 SDK 代碼，用於不同平台上的實現，便於開發者進行接口測試。
- 優化團隊協作：OpenAPI 有一個強大的社區，裏面有許多強悍的貢獻者，可以幫助團隊更好地進行協作開發。
- 方便接口管理：如果能夠自動化生成文檔，就可以減少手動編寫文檔和維護文檔的麻煩，每次接口有變動時也可以自動更新文檔，便於接口的管理和維護。
Swagger 文檔介紹
Swagger 是一種用於 RESTful API 的開源框架，可以幫助開發者快速構建和文檔化 API。Swagger 文檔提供了一種自動生成和可視化 API 文檔的方式，使得 API 的設計和使用更加簡單和易懂。Swagger 文檔通過描述 API 的路徑、參數、請求體、響應和錯誤碼等信息，讓開發者可以快速瞭解 API 的設計和使用方式，方便開發者進行 API 的集成和調用。
Swagger 2.0 是 Swagger 規範的第二個版本，引入了許多新的功能和改進。與第一個版本相比，Swagger 2.0 添加了對 WebSockets、OAuth2、文件上傳和下載等功能的支持，並且提高了描述 API 的精確度和可讀性。Swagger 2.0 還提供了一種可擴展的方式，讓開發者可以為自己的 API 添加自定義的元數據信息。
OpenAPI 3.0 是 Swagger 的下一代規範，為 RESTful API 提供了一種標準的描述和交互方式。與 Swagger 2.0 相比，OpenAPI 3.0 提供了更嚴格的模式驗證和錯誤處理，支持更多的數據類型和協議，同時還提供了更好的安全性和可擴展性。OpenAPI 3.0 還提供了更好的分層描述方式，讓開發者可以更好地組織和管理 API 的文檔。
那麼我們怎麼在 Django 項目中集成 Swagger 功能呢？我介紹兩個工具 drf-yasg 和 drf-spectacular。
drf-yasg 介紹
https://github.com/axnsan12/drf-yasg
drf-yasg 也是一個基於 DRF 的 API 文檔生成工具，同樣支持 Swagger 2.0規範，並提供了自動生成文檔和交互式文檔頁面的功能。它的特點是支持動態生成 Swagger UI，支持多種主題，可以自定義 API 文檔樣式，同時也提供了一些有用的功能，比如支持在文檔中隱藏指定字段、支持在文檔中添加額外的參數等。
drf-spectacular介紹
https://github.com/tfranzel/drf-spectacular
drf-spectacular 是一個基於 DRF 的 API 文檔生成工具，支持 OpenAPI 3.0規範，並提供了自動生成文檔和交互式文檔頁面的功能。它支持自定義的擴展和重載，可以滿足不同項目的需求，同時還提供了一些有用的功能，比如支持通過代碼自動註冊 API 視圖、支持自定義請求和響應驗證器等。
使用 drf-spectacular 自動生成 OpenAPI 3.0 文檔
如果新使用的是 OpenAPI 3.0 的文檔，那麼只能採用的是 drf-spectacular。
1、安裝 drf-spectacula
pip install drf-spectacular2、必要的配置
在 settings.py 中聲明
INSTALLED_APPS = [ # ALL YOUR APPS'drf_spectacular',]註冊到 DRF Django Rest Framework
REST_FRAMEWORK = {# YOUR SETTINGS'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',}3、自定義OpenApi 描述
SPECTACULAR_SETTINGS = {'TITLE': 'Your Project API','DESCRIPTION': 'Your project description','VERSION': '1.0.0','SERVE_INCLUDE_SCHEMA': False,# OTHER SETTINGS}REST_FRAMEWORK = { # YOUR SETTINGS'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',}
drf-spectacular ships with sane default settings that should work reasonably well out of the box. It is not necessary to specify any settings, but we recommend to specify at least some metadata.
SPECTACULAR_SETTINGS = {'TITLE': 'Your Project API','DESCRIPTION': 'Your project description','VERSION': '1.0.0','SERVE_INCLUDE_SCHEMA': False, # OTHER SETTINGS}4、生成 yaml 文件
./manage.py spectacular --color --file schema.yml5、可視化打開 swagger 文件(可選)
docker run -p 80:8080 -e SWAGGER_JSON=/schema.yml -v ${PWD}/schema.yml:/schema.yml swaggerapi/swagger-ui我們可以看到 Swagger UI 如下：
更多 Swagger 使用技巧：
- 寫給全棧工程師的 Swagger 基礎教程
- 如何使用 Swagger 自動生成 API 文檔
