Python Django：添加 Swagger 支持

Nephilim 2023-10-24

Tips：一些记录，一些笔记

2023/10/24

TUESDAY

活着，就是在死去的过程，一天一天的，向着死亡的方向接近。所以不必保留，要随心所欲地生活。

—— 《不是任何人女儿的海媛》

Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

现在「SWAGGER」官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Swagger 官方网站：https://swagger.io/

Swagger 官方GITHUB网站：https://github.com/swagger-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	drf-spectacular
https://github.com/axnsan12/drf-yasg	https://github.com/tfranzel/drf-spectacular
drf-yasg 也是一个基于 DRF 的 API 文档生成工具，同样支持 Swagger 2.0规范，并提供了自动生成文档和交互式文档页面的功能。它的特点是支持动态生成 Swagger UI，支持多种主题，可以自定义 API 文档样式，同时也提供了一些有用的功能，比如支持在文档中隐藏指定字段、支持在文档中添加额外的参数等。	drf-spectacular 是一个基于 DRF 的 API 文档生成工具，支持 OpenAPI 3.0规范，并提供了自动生成文档和交互式文档页面的功能。它支持自定义的扩展和重载，可以满足不同项目的需求，同时还提供了一些有用的功能，比如支持通过代码自动注册 API 视图、支持自定义请求和响应验证器等。

PIP安装依赖包

使用Python的PIP工具安装：

(venv) adamhuan@Leviathan djangoFeather % pip install drf-spectacular
Looking in indexes: https://mirrors.aliyun.com/pypi/simple/
Collecting drf-spectacular
  Downloading https://mirrors.aliyun.com/pypi/packages/f2/f7/118bc5eccedf0cf3ce0e1b09edd1bdb8becf778e92dc5f30ad339ee771c1/drf_spectacular-0.26.5-py3-none-any.whl (94 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 94.1/94.1 kB 1.5 MB/s eta 0:00:00
Requirement already satisfied: Django>=2.2 in ./venv/lib/python3.10/site-packages (from drf-spectacular) (4.2.6)
Requirement already satisfied: djangorestframework>=3.10.3 in ./venv/lib/python3.10/site-packages (from drf-spectacular) (3.14.0)
Requirement already satisfied: uritemplate>=2.0.0 in ./venv/lib/python3.10/site-packages (from drf-spectacular) (4.1.1)
Collecting PyYAML>=5.1 (from drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/5b/07/10033a403b23405a8fc48975444463d3d10a5c2736b7eb2550b07b367429/PyYAML-6.0.1-cp310-cp310-macosx_11_0_arm64.whl (169 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 169.3/169.3 kB 3.8 MB/s eta 0:00:00
Collecting jsonschema>=2.6.0 (from drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/0f/bf/a84bc75f069f4f156e1c0d9892fb7325945106c6ecaad9f29d24360872af/jsonschema-4.19.1-py3-none-any.whl (83 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 83.3/83.3 kB 7.0 MB/s eta 0:00:00
Collecting inflection>=0.3.1 (from drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/59/91/aa6bde563e0085a02a435aa99b49ef75b0a4b062635e606dab23ce18d720/inflection-0.5.1-py2.py3-none-any.whl (9.5 kB)
Requirement already satisfied: asgiref<4,>=3.6.0 in ./venv/lib/python3.10/site-packages (from Django>=2.2->drf-spectacular) (3.7.2)
Requirement already satisfied: sqlparse>=0.3.1 in ./venv/lib/python3.10/site-packages (from Django>=2.2->drf-spectacular) (0.4.4)
Requirement already satisfied: pytz in ./venv/lib/python3.10/site-packages (from djangorestframework>=3.10.3->drf-spectacular) (2023.3.post1)
Collecting attrs>=22.2.0 (from jsonschema>=2.6.0->drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/f0/eb/fcb708c7bf5056045e9e98f62b93bd7467eb718b0202e7698eb11d66416c/attrs-23.1.0-py3-none-any.whl (61 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 61.2/61.2 kB 5.6 MB/s eta 0:00:00
Collecting jsonschema-specifications>=2023.03.6 (from jsonschema>=2.6.0->drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/1c/24/83349ac2189cc2435e84da3f69ba3c97314d3c0622628e55171c6798ed80/jsonschema_specifications-2023.7.1-py3-none-any.whl (17 kB)
Collecting referencing>=0.28.4 (from jsonschema>=2.6.0->drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/be/8e/56d6f1e2d591f4d6cbcba446cac4a1b0dc4f584537e2071d9bcee8eeab6b/referencing-0.30.2-py3-none-any.whl (25 kB)
Collecting rpds-py>=0.7.1 (from jsonschema>=2.6.0->drf-spectacular)
  Downloading https://mirrors.aliyun.com/pypi/packages/ca/d8/b3948ba2d8651ec4681e61cd884d16ecd6145fa6ee760cb8817a7a9dacc6/rpds_py-0.10.6-cp310-cp310-macosx_11_0_arm64.whl (323 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 323.1/323.1 kB 3.4 MB/s eta 0:00:00
Requirement already satisfied: typing-extensions>=4 in ./venv/lib/python3.10/site-packages (from asgiref<4,>=3.6.0->Django>=2.2->drf-spectacular) (4.8.0)
Installing collected packages: rpds-py, PyYAML, inflection, attrs, referencing, jsonschema-specifications, jsonschema, drf-spectacular
Successfully installed PyYAML-6.0.1 attrs-23.1.0 drf-spectacular-0.26.5 inflection-0.5.1 jsonschema-4.19.1 jsonschema-specifications-2023.7.1 referencing-0.30.2 rpds-py-0.10.6


[notice] A new release of pip is available: 23.2.1 -> 23.3.1
[notice] To update, run: pip install --upgrade pip
(venv) adamhuan@Leviathan djangoFeather % 
(venv) adamhuan@Leviathan djangoFeather % pip list | grep "drf-spe"  
drf-spectacular           0.26.5


[notice] A new release of pip is available: 23.2.1 -> 23.3.1
[notice] To update, run: pip install --upgrade pip
(venv) adamhuan@Leviathan djangoFeather %

Django中的配置

文件：「setting.py」

INSTALLED_APPS = [
    'drf_spectacular',
]

修改 DRF 的配置：

文件：「setting.py」

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema'
}

添加 Spectacular 的配置：

文件：「setting.py」

SPECTACULAR_SETTINGS = {
    # 自定义 OpenAPI 描述信息
    'TITLE': 'Feather API',
    'DESCRIPTION': '「鸿毛」系统：API文档',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

数据模型类（MODEL）：样例

文件：「helloworld/models.py」

from django.db import models


# Create your models here.


class Books(models.Model):
    name = models.CharField(max_length=60)
    desc = models.TextField(max_length=1000, blank=True, null=True)


    class Meta:
        verbose_name = '书籍'
        verbose_name_plural = verbose_name


    def __str__(self):
        return self.name

添加到Django的Admin管理后台中：

文件：「helloworld/admin.py」

from django.contrib import admin


from .models import *


# Register your models here.


# class: Book


class BookAdmin(admin.ModelAdmin):
    fields = ('name', 'desc')


admin.site.register(Books, BookAdmin)

数据模型类：配置好Rest Framework

数据模型类配置 DRF（Django Rest Framework）可以参考上一篇文档「Python Django：添加 Rest Framework 支持」，里面有详细的描述与说明。

路由（ROUTER）：根路由配置

文件：「urls.py」

"""
URL configuration for djangoFeather project.


The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/4.2/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""
from django.contrib import admin
from django.urls import path,include


from drf_spectacular.views import SpectacularJSONAPIView, SpectacularRedocView, SpectacularSwaggerView


urlpatterns = [
    path('admin/', admin.site.urls),


    path('helloworld/', include('helloworld.urls')),


    # Swagger
    path('swagger/json/', SpectacularJSONAPIView.as_view(), name='schema'),
    
    # Swagger: Optional UI
    path('swagger/ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('swagger/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),


]