什么是 Swagger
Swagger 是一个流行的 RESTful API 的设计工具，提供自动生成 API 文档的功能，可以使得 API 文档更加规范化并且易于阅读和理解。Swagger 可以根据 API 的定义文件自动生成 API 的文档，所以可以避免手写文档的重复工作，并且可以保持文档与代码同步。
Django RESTful API 中的 Swagger
Django REST framework 提供了一个用于 API 文档自动生成的库，即 drf-yasg，它可以根据 Django RESTful API 中的视图函数和模型自动生成 API 文档的 Swagger 格式定义。这里将介绍如何在 Django RESTful API 应用中使用 drf-yasg 来自动生成 Swagger 文档。
步骤
1. 安装 drf-yasg
可以使用 pip 安装 drf-yasg：
pip install drf-yasg
2. 配置 settings.py
首先，需要将 drf-yasg 加入 INSTALLED_APPS 中：
INSTALLED_APPS = [
...
'drf_yasg',
...
]然后，在 settings.py 中增加如下的配置：
SWAGGER_SETTINGS = {
'DEFAULT_INFO': 'myapp.api.urls.openapi_info', # API 文档的信息
'DEFAULT_GENERATOR_CLASS': 'drf_yasg.generators.OpenAPISchemaGenerator', # 使用 OpenAPI 格式
'DEFAULT_API_URL': 'https://example.com/', # API 的根 URL
'DEFAULT_API_VERSION': 'v1', # API 的版本
'DEFAULT_AUTO_SCHEMA_CLASS': 'myapp.api.schema.CustomAutoSchema', # 使用自定义的 Schema
}其中，API 文档的信息可以使用下面这个函数生成：
-- -------------------- ---- -------
---- ----------- ------ -------
---- ------------------------ ------ ------------ -- -
--- ---------------------------
---
--------- ------- ---- ------- --- --- --- --------------
---
---- -------- ------ -------
------ -------------
-------------- ------
---------------------
-------------------- --- --------------
--------------------------------------------------
-----------------------------------------------------
------------------------
--------- ---------
-----------------------------------------
-
-3. 编写 views.py
在 views.py 中，在 Django RESTful API 的视图函数中增加如下注释，定义视图函数的参数、返回值和响应状态码：
-- -------------------- ---- -------
---- -------- ------ -------
---- -------------- ------ ---------------
---- -------------- ------ -------------------
---- -------------- ------ --------- ------------ -----------
---- ----------------------- ------ --------
---- -------------------- ------ -------
----- ------------------------------------------
---- - -----------------------
--- - -----------------------
----- ---------------------------------
---
------------ ----
-----------
- ---- - ----
----------- - ----
-------- - ----
---- - ------
-------- - -----
- ---- - ---
----------- - ----
-------- - ----
---- - -------
-------- - -----
----------
----
------------ -------
-------
----- ------
-----------
-------
----- ------
-------- -------
-----
----- ------
-----------
-----
----- ------
-------- --
----
----- -------
-------- --
---
---------------- - -----------------
------------------ - ----------------------
--- --------- -------- ------ ----------
---- - --------------------------------
--- - -------------------------------
------ ------------------- ---------- ------- -------- ----- ------ ------4. 编写 urls.py
在 urls.py 中，增加如下代码：
-- -------------------- ---- -------
---- -------------- ------ ---------------
---- -------- ------ -------
----------- - ----------------
-------------
------------ -----
---------------------
------------------ --- -------------
--------------------------------------------------
-----------------------------------------------------
--------------------------------- ----------
--
-------------------------
------------
------------------------------------------
-
----------- - -
--------------- ------------------------------ ----------------- --------------------------
---------------- ---------------------------- ----------------- ---------------------
---
-其中，我们定义了两个 URL，一个用来接收 Swagger 文档请求，另一个用来显示文档，使用了 Swagger UI 和 ReDoc 两个工具。
5. 运行应用
在终端中运行如下命令，启动 Django RESTful API 应用：
python manage.py runserver
然后，在浏览器中输入 http://127.0.0.1:8000/docs 即可访问生成的 Swagger 文档。
总结
Django RESTful API 中使用 drf-yasg 可以方便地生成 Swagger 格式的 API 文档，避免手写文档带来的重复繁琐。同时，在视图函数中使用注释的方式，能够更加清晰地定义 API 接口的参数、返回值和状态码，文档的可读性也更加强。
示例代码
完整示例代码可以在 GitHub 上查看。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65b4de45add4f0e0ffdb90df