【接口文档】Django restful framework中自动生成API文档

Django restful framework中自动生成API文档

一、Swagger概述

1.引言

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

2.Swagger简介

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

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

二、Swagger安装和配置

参考官网：https://github.com/marcgibbons/django-rest-swagger

自动生成api文档（不管是函数视图还是类视图都能显示）

1.安装rest_framework_swagger库

pip install django-rest-swagger

2.在项目下的 urls.py 中加入如下：

from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='API文档')
urlpatterns += [
    path(r'docs/', schema_view),
]

3.在创建的django项目下的settings中加入如下：

INSTALLED_APPS = ['rest_framework_swagger',]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'
}

4、生成的api文档界面如下：

可以通过定义注释格式来设置接口备注信息

5、DRF访问接口自带的界面如下：

更多分享以及Python之基础知识大全关注公众号【刘旺學長】