Django Rest Swagger 编写API文档教程

关于Swagger

Swagger是REST API文档生成工具之一，知名度蛮高的，其好处有以下：

• 简单：一般的web框架都有大牛写的swagger第三方，只需要简单的部署安装，开发者即可立即编写API文档。
• 易于维护：通过修改相应的注释，即可快速的呈现在界面上，同时对于后期代码的维护也有一定的帮助。
• 便捷：开发中无需单独再另外花时间去编写接口，在当下流行采用前后端分离这种开发模式的项目，降低了沟通成本。
• 强大的社区： Swagger 有一个强大的社区，里面有许多强悍的贡献者。

使用教程

教程代码地址

开发环境

python==3.5
django==2.1.3
djangorestframework==3.9.0
django-rest-swagger==2.2.0

注意事项

• 如果django的版本高于3.0，Django REST Swagger就不再支持了，这个时候需要用drf-yasg作为编写接口的第三方库

安装

pip install Django==2.1.3
pip install djangorestframework==3.9.0
pip install django-rest-swagge==2.2.0

note

• 以下步骤是基于已经创建好django项目的

配置settings文件

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 以下需要加入到apps中的
    'rest_framework',
    'rest_framework_swagger',
    # 这个是新建的一个app
    'snippets'

]

# 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,
}

配置项目的urls.py

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

# 路由
router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet, base_name='users')
router.register(r'groups', views.GroupViewSet, base_name='groups')
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
    # swagger接口文档路由
    url(r'^docs/', schema_view, name="docs"),
	]

编写API文档

方式一

from django.contrib.auth.models import User, Group
from rest_framework import viewsets

from snippets.serializers import UserSerializer, GroupSerializer


class UserViewSet(viewsets.ModelViewSet):

    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer

    def create(self, request, *args, **kwargs):
        """
        ### 新增用户的接口
        #### 请求方法
            - post

        #### 请求格式
            - json

        #### 请求参数
        | 字段名| 含义  | 类型   | 是否必填   |  示例  |
        |:------:|:------:|:------:|:------:|:------:|
        | first_name | 姓    |  string |是 |李 |
        | last_name | 名    |  string |是 |四 |
        | password | 密码  |  string |是 |test |
        | email | 邮箱    |   string |是 |test@163.com |

        #### 返回参数
        | 字段名| 含义  | 类型   |
        |:------:|:------:|:------:|
        | code | 状态码    |  int |
        | message | 附加消息    |
        | data | 数据  |  dict |

        #### 返回格式
            -json

        #### 返回示例
            - {"code": 0, "message": "success", "data":{}}
        """
        super(UserViewSet, self).create(self, request, *args, **kwargs)

最终效果

方式二

class AbstractUser(AbstractBaseUser, PermissionsMixin):
    """
    An abstract base class implementing a fully featured User model with
    admin-compliant permissions.

    Username and password are required. Other fields are optional.
    """
    username_validator = UnicodeUsernameValidator()

    username = models.CharField(
        _('username'),
        max_length=150,
        unique=True,
        help_text=_('Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.'),
        validators=[username_validator],
        error_messages={
            'unique': _("A user with that username already exists."),
        },
    )
    first_name = models.CharField(_('first name'), max_length=30, blank=True)
    last_name = models.CharField(_('last name'), max_length=150, blank=True)
    email = models.EmailField(_('email address'), blank=True)
    is_staff = models.BooleanField(
        _('staff status'),
        default=False,
        help_text=_('Designates whether the user can log into this admin site.'),
    )
    is_active = models.BooleanField(
        _('active'),
        default=True,
        help_text=_(
            'Designates whether this user should be treated as active. '
            'Unselect this instead of deleting accounts.'
        ),
    )
    date_joined = models.DateTimeField(_('date joined'), default=timezone.now)

    objects = UserManager()

    EMAIL_FIELD = 'email'
    USERNAME_FIELD = 'username'
    REQUIRED_FIELDS = ['email']

    class Meta:
        verbose_name = _('user')
        verbose_name_plural = _('users')
        abstract = True

说明

• Django Rest Swagger会自动搜索当前视图所使用到的serializer_class作为搜索对象，将序列化的模型中各个字段的数据类型和help_text展示出来

最总效果

感受

• 上面两种方式确实有一定的便捷性，但是，给我的感觉却不太友好。
• 方式一的写法虽然和平时的写的markdown差不多，但是大幅增加的代码长度，使代码不再简洁。
• 方式二的写法不够清晰，接口中很多需要注意的地方都不能清晰的表达出来。
• 以上只是我个人简单的感受。毕竟比较少使用swagger写接口文档，有很多强大的功能都不清楚，所以有不对或者是其他不好的地方，请指出来，谢谢。