使用Swagger生成RESTful API文档的Django项目实践

什么是Swagger？

Swagger是一个用于生成、描述、调用和可视化RESTful风格的Web服务的规范和完整框架。其总体目标是实现客户端和文件系统与服务器同步更新的速度，通过将文件的方法、参数和模型紧密集成到服务器端的代码中。

Swagger的作用：

1. 接口文档在线自动生成。
2. 功能测试。

Swagger的优势：

1. 生成具有互动性的API控制台，方便开发者学习和尝试API。
2. 生成客户端SDK代码，适用于不同平台（例如Java、Python等）的实现。
3. 从代码注释中自动生成Swagger文件。
4. 强大的社区支持，有许多贡献者。

在Django RESTful项目中使用Swagger：

安装：

pip install django-rest-swagger

添加到 Django 设置中。’rest_framework_swagger’INSTALLED_APPS

settings.py

<code>INSTALLED_APPS = [</code><code><br></code><code> ...</code><code><br></code><code> 'rest_framework_swagger',</code><code><br></code><code> ...</code><code><br></code><code>]</code>

urls.py添加路由

<code>from django.conf.urls import url</code><code>from rest_framework_swagger.views import get_swagger_view</code><code><br></code><code>schema_view = get_swagger_view(title='Pastebin API')</code><code><br></code><code>urlpatterns = [</code><code>    url(r'^$', schema_view)</code><code>]</code>

在浏览器中查看

在settings.py添加额外配置项

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

高级部分：

Django REST Swagger包含两个渲染器，OpenAPIRenderer和SwaggerUIRenderer。OpenAPIRenderer生成JSON规范，SwaggerUIRenderer负责UI呈现。要呈现UI，必须包含两个渲染器。

可以自定义区域：

<code>● {% block extra_styles %}添加其他样式表</code><code>● {% block extra_scripts %}添加其他脚本。</code><code>● {% block user_context_message %}自定义“你好，用户”消息（仅限 Django 会话）</code><code>● {% block extra_nav %}导航栏中其他内容的占位符。</code><code>● {% block logo %}导航栏的徽标区域。</code>

Swagger模板定制：

通过覆盖路径site-packages/rest_framework_swagger/templates/rest_framework_swagger/index.html文件的部分代码来实现页面定制。可自定义区域包括添加其他样式表、脚本、自定义用户消息、导航栏中其他内容等。

解决报错信息：

如果出现”‘staticfiles’ is not a registered tag library”错误，可将{% load staticfiles %}修改为新语法{% load static %}。