Django-rest-framework swagger文档

 

 

 

Django REST framework 是用于构建Web API 的强大而灵活的工具包。

我们可能想使用REST框架的一些原因:

• Web浏览API对于开发人员来说是一个巨大的可用性。
• 认证策略包括OAuth1a和OAuth2的包。
• 支持ORM和非ORM数据源的序列化。
• 如果你不需要更强大的功能，就可以使用常规的基于功能的视图。
• 广泛的文档和良好的社区支持。
• 包括Mozilla、Red Hat、Heroku和Eventbrite在内的国际知名公司使用和信任。

 Swagger是一个API开发者的工具框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统服务器以同样的速度来更新，方法，参数和模型紧密集成到服务器端的代码中，允许API始终保持同步。

 

准备环境

python 3.7.3

Django 2.2.4

djangorestframework==3.9.2

django-rest-swagger 2.2.0

pip install -U django==2.1.5
pip install djangorestframework==3.9.2
pip install django-rest-swagger

 

Pycharm创建一个项目

 

 

修改配置文件

 t_swagger/settings.py，增加2行

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

 

 在swagger/settings.py末尾处，增加Swagger配置

# swagger 配置项
SWAGGER_SETTINGS = {
    # 基础样式
    'SECURITY_DEFINITIONS': {
        "basic":{
            'type': 'basic'
        }
    },
    # 如果需要登录才能够查看接口文档, 登录的链接使用restframework自带的.
    'LOGIN_URL': 'rest_framework:login',
    'LOGOUT_URL': 'rest_framework:logout',
    # 'DOC_EXPANSION': None,
    # 'SHOW_REQUEST_HEADERS':True,
    # 'USE_SESSION_AUTH': True,
    # 'DOC_EXPANSION': 'list',
    # 接口文档中方法列表以首字母升序排列
    'APIS_SORTER': 'alpha',
    # 如果支持json提交, 则接口文档中包含json输入框
    'JSON_EDITOR': True,
    # 方法列表字母排序
    'OPERATIONS_SORTER': 'alpha',
    'VALIDATOR_URL': None,
}

进入api(应用目录)，新建文件serializers.py

# 序列化
from django.contrib.auth.models import User,Group
from  rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = "__all__"

class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = "__all__"

 

 

将django自带的2个表，进行序列化

 

进入api(应用目录)，修改views.py

from django.shortcuts import render, HttpResponse
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:
            返回用户实例
        list:
            返回所有用户，按最近加入的用户排序
        create:
            创建新用户
        delete:
            删除现有用户
        partial_update:
            更新现有用户上的一个或多个字段
        update:
            更新用户
    """
    '''查看，编辑用户的界面'''
    queryset = User.objects.all().order_by('id')
    serializer_class = UserSerializer
    print(serializer_class, type(serializer_class))


class GroupViewSet(viewsets.ModelViewSet):
    '''
        retrieve:
            返回组实例
        list:
            返回按最近加入的组排序的所有组
        create:
            创建新组
        delete:
            删除现有组
        partial_update:
            更新现有组上的一个或多个字段
        update:
            更新一个组
    '''
    '''查看，编辑组的界面'''
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

 

注意：这里不需要return，它会返回表数据的。

 

修改文件t_swagger/urls.py

from django.contrib import admin
from django.urls import path,include
from rest_framework import routers  # 路由配置模块
from api import views

# 路由
router = routers.DefaultRouter()
router.register(r'users',views.UserViewSet,base_name='user')
router.register(r'groups',views.GroupViewSet)

# 重要的是如下三行
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title='Users 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'),
]

 

生成表

python manage.py makemigrations --empty api
python manage.py migrate

 

python manage.py createsuperuser

 

启动项目

python manage.py runserver

 

 

访问页面

http://127.0.0.1:8000/

 

http://127.0.0.1:8000/docs/