前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >Django Swagger接口文档生成

Django Swagger接口文档生成

作者头像
py3study
发布2020-08-06 10:54:41
4K0
发布2020-08-06 10:54:41
举报
文章被收录于专栏:python3python3

一、概述

引言

当接口开发完成,紧接着需要编写接口文档。传统的接口文档使用Word编写,or一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次接口有变更,需要手动修改接口文档。为了改善这种情况,推荐使用Swagger来管理接口文档,实现接口文档的自动更新。

简介

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

1.png
1.png

如:接口测试站点(http://httpbin.org/#/),也是利用Swagger来生成接口文档

Swagger优势

1)Swagger可生成一个具有互动性的API控制台,开发者可快速学习和尝试API 2)Swagger可生成客户端SDK代码,用于不同平台上(Java、Python...)的实现 3)Swagger文件可在许多不同的平台上从代码注释中自动生成 4)Swagger有一个强大的社区,里面有许多强悍的贡献者

二、Django接入Swagger

大致步骤

代码语言:javascript
复制
1.安装django-rest-swagger
2.进入到setting.py文件,添加django-rest-swagger应用
3.进入到views.py,将之前定义的UserViewSet和GroupViewset补充注释
4.在urls.py中添加get_schema_view辅助函数
5.启动Django服务,检测Swagger接口文档配置效果

环境说明

代码语言:javascript
复制
python 3.7.3

Django 2.2.4

djangorestframework==3.9.2

django-rest-swagger 2.2.0

安装模块

代码语言:javascript
复制
pip3 install djangorestframework==3.9.2

注意:djangorestframework版本不能高于3.9.2,否则访问/docs/出现以下错误。

代码语言:javascript
复制
Expected a `coreapi.Document` instance

按照网友的意思,Django Swagger模块已经不维护了,只能支持到3.9.2

另外,django版本不能大于3.x。

配置setting.py

使用Pycharm新建一个项目:t_swagger,app名为api

1.png
1.png

 修改t_swagger/settings.py,增加2行

代码语言:javascript
复制
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配置

代码语言:javascript
复制
# 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,
}

配置serializers.py

进入api(应用目录),新建文件serializers.py,内容如下:

代码语言:javascript
复制
# 序列化
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个表,进行序列化。

配置views.py

进入api(应用目录),修改views.py,完整内容如下:

代码语言:javascript
复制
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,它会返回表数据的。

配置urls.py

修改文件t_swagger/urls.py,完整内容如下:

代码语言:javascript
复制
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'),
]

生成表

代码语言:javascript
复制
python3 manage.py makemigrations
python3 manage.py migrate

创建超级用户

代码语言:javascript
复制
python3 manage.py createsuperuser

注意:密码必须符合复杂性要求。

启动项目

直接使用Pycharm启动即可。

三、访问页面

drf自带的接口UI

代码语言:javascript
复制
http://127.0.0.1:8000/

效果如下:

1.png
1.png

Swagger UI

代码语言:javascript
复制
http://127.0.0.1:8000/docs/

效果如下:

1.png
1.png

点击users

1.png
1.png

点击get-->try it out

1.png
1.png

点击执行

1.png
1.png

结果如下:

1.png
1.png

这里是返回了一条用户表数据,"username": "xiao",就是我新建的超级用户。

点击Authorize

1.png
1.png

输入新建的超级用户和密码

1.png
1.png

 登录成功后,效果如下:

1.png
1.png

本文参考链接:

https://www.jianshu.com/p/c53de96f3ff1

https://blog.csdn.net/sinat_41622641/article/details/81636682

https://blog.csdn.net/the_brave/article/details/106138396

本文参与 腾讯云自媒体分享计划,分享自作者个人站点/博客。
原始发表:2020-08-03 ,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 一、概述
    • 引言
      • 简介
        • Swagger优势
        • 二、Django接入Swagger
          • 大致步骤
            • 环境说明
              • 安装模块
                • 配置setting.py
                  • 配置serializers.py
                • 配置views.py
                  • 配置urls.py
                    • 生成表
                    • 创建超级用户
                  • 启动项目
                  • 三、访问页面
                    • drf自带的接口UI
                      • Swagger UI
                      领券
                      问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档