Restful接口开发与测试—集成Swagger

清风穆云

发布于 2021-08-09 11:25:25

6590

发布于 2021-08-09 11:25:25

文章被收录于专栏：QA一隅

Swagger接口文档生成

接口开发完成了，那么接下来需要编写接口文档。传统的接口文档编写都是使用Word或者其他一些接口文档管理平台，这种形式接口文档维护更新比较麻烦，每次接口有变动时得手动修改文档。因此，针对这种情况，这里推荐使用Swagger来管理接口文档。

Swagger简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统(源代码)作为服务器以同样的速度来更新。每当接口有变动时，对应的接口文档也会自动更新。

Tips：http://httpbin.org/#/ 也是利用Swagger生成接口文档。

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Django 接入Swagger

首先安装 django-rest-swagger

pip install django-rest-swagger

进入到setting.py文件，添加django-rest-swagger应用

# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'api',
    'rest_framework_swagger',
]

进入到views.py将之前定义的UserViewSet和GroupViewSet补充注释：


from django.contrib.auth.models import User,Group
from rest_framework import viewsets
from api.serializers import UserSerializer,GroupSerializer

# Create your views here.
class UserViewSet(viewsets.ModelViewSet):
    """
        retrieve:
            Return a user instance.

        list:
            Return all users, ordered by most recently joined.

        create:
            Create a new user.

        delete:
            Remove an existing user.

        partial_update:
            Update one or more fields on an existing user.

        update:
            Update a user.
        """
    queryset = User.objects.all()
    serializer_class = UserSerializer

class GroupViewSet(viewsets.ModelViewSet):
    """
        retrieve:
            Return a group instance.

        list:
            Return all groups, ordered by most recently joined.

        create:
            Create a new group.

        delete:
            Remove an existing group.

        partial_update:
            Update one or more fields on an existing group.

        update:
            Update a group.
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

在urls.py 添加get_schema_view辅助函数

from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer

schema_view=get_schema_view(title='API',renderer_classes=[OpenAPIRenderer,SwaggerUIRenderer])

urlpatterns = [
    path('admin/', admin.site.urls),
    path('',include(router.urls)),
    path('api-auth/',include('rest_framework.urls',namespace='rest_framework')),
    path('docs/',schema_view,name='docs')
]

启动服务，然后打开地址：http://127.0.0.1:8000/docs/ 即可看到如下界面：