解锁API文档自动化魔力：探索drf-yasg

引言

我们知道在后端开发的时候接口文档非常的重要，django本身具有内置的生成API接口文档的功能，但是无奈的是，生成的接口文档太丑了，于是我们开始了寻求第三方插件的道路，巧了，正好有一块插件 drf-yasg，它能够满足我们的需求，真正实现了从Django Rest Framework API生成真正的Swagger/OpenAPI 2.0规范。

在现代软件开发中，构建可靠且易于理解的API文档至关重要。Django REST框架（DRF）作为Python中最受欢迎的Web框架之一，提供了强大的工具来构建灵活的API。然而，手动编写和维护API文档可能会变得繁琐且容易出错。为了解决这个问题，开发人员转向自动化工具，其中一个备受推崇的选择就是drf-yasg。

drf-yasg是一个基于DRF的API工具，它可以自动生成交互式的Swagger UI和OpenAPI规范，使得API文档的创建过程更加简单、快捷。通过drf-yasg，开发人员可以轻松地生成详细的API文档，提高开发效率，同时为团队成员和外部用户提供清晰的接口文档，促进协作与集成。

本文将深入探讨drf-yasg的特性、用法以及如何将其集成到您的项目中，以便您充分利用这一强大工具，提升API开发的效率和质量。

兼容性

Django Rest Framework：3.10、3.11、3.12 Django：2.2、3.0、3.1 Python：3.6、3.7、3.8、3.9

仅支持Python、Django和Django REST框架的每个major.minor系列的最新补丁版本。

仅支持最新版本的drf-yasg。随着新版本的发布，对旧版本的支持将立即取消。在升级到当时可用的最新版本之前，请不要制造问题。回归报告已被接受，并将尽快通过新版本解决。删除的功能通常会经历几个小版本的弃用周期。

参考链接

来源：https://github.com/axnsan12/drf-yasg/ 文档：https://drf-yasg.readthedocs.io/ 更改日志：https://drf-yasg.readthedocs.io/en/stable/changelog.html 现场演示：https://drf-yasg-demo.herokuapp.com/

OpenAPI 3.0说明

如果你想将Swagger/OpenAPI支持添加到一个新项目中，你可能想看看drf壮观，这是一个积极维护的新库，它共享了这个项目的大部分目标，同时使用OpenAPI 3.0方案。

在可以描述的API类型中，OpenAPI 3.0比2.0提供了更多的灵活性。drf-yasg不太可能很快（如果有的话）获得对OpenAPI 3.0的支持。

特征

完全支持嵌套的序列化程序和架构
响应方案和说明
与codegen工具兼容的模型定义
规范生成过程中所有点的定制挂钩
规范的JSON和YAML格式
捆绑最新版本的swaggerui和redoc以查看生成的文档
架构视图是现成的可缓存视图
生成的Swagger模式可以由Swagger规范验证器自动验证
支持Django REST框架API版本控制，支持URLPathVersioning和命名空间版本控制；当前不支持其他DRF或
自定义版本控制方案

项目截图如下：

完全嵌套的请求和响应方案。

在redoc和swagger ui之间进行选择。

真实模型定义。

操作演示

0、安装首选的安装方法直接来自pypi：

pip install -U drf-yasg

此外，如果您想使用内置的验证机制，您需要安装一些额外的要求：

pip install -U drf-yasg[validation]

在设置.py中：

INSTALLED_APPS=[
    ...
    django.contrib.staticfiles，# 为swagger-ui的css/js文件提供服务所需的#
    'drf_yasg'，
    ...
]

在urls.py中：


from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi


schema_view = get_schema_view(
   openapi.Info(
      title="Snippets API",
      default_version='v1',
      description="Test description",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="contact@snippets.local"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=[permissions.AllowAny],
)

urlpatterns = [
   re_path(r'^swagger(?P<format>.json|.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

这公开了4个端点：

API规范的JSON视图，位于/swagger.JSON
API规范的YAML视图，位于/swagger.YAML
您的API规范的swagger-ui视图在/swagger/
在/ReDoc上的API规范的ReDoc视图/

然后基于此配置就能够在本地访问你的项目接口了；此外，您还可以在settings.py文件中包含更多设置。

https://drf-yasg.readthedocs.io/en/stable/settings.html

总结

在现代Web开发中，API文档的重要性不言而喻。drf-yasg作为一个强大的DRF工具，为开发人员提供了自动生成API文档的便利性和灵活性。通过本文的介绍，您应该对drf-yasg有了更深入的了解，了解了它的优势以及如何利用它来简化和改进您的API文档工作流程。无论您是个人开发者还是团队中的一员，掌握drf-yasg都能够为您的项目带来更好的开发体验和更清晰的文档展示。