Django Rest Framework：如何为基于函数的视图启用 swagger 文档

Django

如何为基于函数的视图启用 Swagger 文档

在使用 Django Rest Framework（DRF）开发 Web API 时，为了方便文档的编写和查看，我们常常需要使用 Swagger 这样的工具来自动生成接口文档。DRF 提供了一个名为 drf-yasg 的扩展，可以帮助我们为基于函数的视图启用 Swagger 文档。

安装和配置 drf-yasg

首先，我们需要安装 drf-yasg 扩展。可以通过 pip 命令来进行安装：

pip install drf-yasg

安装完成后，我们需要在 Django 项目的 settings.py 文件中进行配置。将 drf-yasg 添加到 INSTALLED_APPS 中：

Python
INSTALLED_APPS = [
    ...
    'drf_yasg',
    ...
]

在同一个文件中，我们还需要添加一些额外的配置项，以告诉 drf-yasg 文档的相关信息。在 settings.py 文件的末尾添加以下内容：

Python
SWAGGER_SETTINGS = {
    'DEFAULT_INFO': 'your_project.urls.swagger_info',
}

上述配置中，'your_project.urls.swagger_info' 是一个用于存放文档信息的函数的路径。我们需要在项目的 urls.py 文件中创建这个函数。打开 urls.py 文件，添加以下内容：

Python
from Django.urls import include, path
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
    openapi.Info(
        title='Your Project API',
        default_version='v1',
        description='API documentation for Your Project',
        terms_of_service='https://www.example.com/policies/terms/',
        contact=openapi.Contact(emAIl='contact@example.com'),
        license=openapi.License(name='BSD License'),
    ),
    public=True,
)
urlpatterns = [
    ...
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    ...
]

在上述代码中，我们创建了一个 schema_view 对象，用于存储文档的信息。在 path('swagger/', ...) 中，我们将 schema_view 与 '/swagger/' 路径进行了绑定，以便在浏览器中查看生成的 Swagger 文档。你可以根据实际情况修改这个路径。

启动服务器并查看 Swagger 文档

配置完成后，我们可以启动服务器，并在浏览器中查看生成的 Swagger 文档了。在终端中运行以下命令启动服务器：

Python manage.py runserver

然后，在浏览器中访问 http://localhost:8000/swagger/，你将看到自动生成的 Swagger 文档。这个文档会显示你在项目中定义的 API 视图、请求参数、响应内容等信息，方便其他开发人员查阅和使用。

在本文中，我们介绍了如何使用 drf-yasg 扩展为基于函数的视图启用 Swagger 文档。通过安装和配置 drf-yasg，我们能够轻松地生成并查看接口文档，提高开发效率。希望这篇文章能够帮助你在使用 Django Rest Framework 开发 Web API 时更好地使用 Swagger。