django搭配swagger编写接口文档

Swagger+django接口文档生成

无论是前端人员还是后端人员，都需要熟悉接口的使用和开发，当接口开发好了，该怎么去具体正确的编写接口文档呢？这可能会使一个很头痛的问题

因为接口可能后期需要变动，如果手动修改接口文档的话，还是比较麻烦的。因此就诞生了很多生成接口文档的工具

目前有很多优秀的api接口文档sdk，不过本篇文章主要介绍一下swagger。

什么是Swagger?

摘录Swagger官方文档的介绍：

1.Swagger UI是一个开源项目，用于可视化地呈现使用OpenAPI (Swagger)规范定义的API的文档。Swagger UI允许您可视化并与API的资源进行交互，而不需要任何适当的实现逻辑，这使得后端实现和客户端消耗变得很容易。

Swagger的优点？

1.改变了以往的word文档编写接口不易修改升级的缺点，使得接口的变化能及时同步更新注释信息。

2.具备多语言的sdk，可以适用于python，java等。

3.Swagger还具备一个具有互动性的api控制台。

django如何集成Swagger

1.安装依赖包

pip install django-rest-swagger

2.配置文件

在settings.py的

INSTALLED_APPS = [
     ···
    'rest_framework_swagger', # api生成文档
	 ···
]

# 配置swagger-ui
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,
}

# 接口框架实例，coreapi.Document的instance
REST_FRAMEWORK = {
	'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}

配置完以上内容后，接下来就是通过restful-framework写自己的api了。

api写完之后，需要配置doc的路由。

在urls.py（具体是在app下还是根项目下都行)中配置路由

from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title='云逸电子商城开发接口文档', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
      ···
      path('docs/',schema_view,name='接口文档'),
	  ···
	  

上述完成后，就可以访问127.0.0.1:8000/docs进行访问

{width=”100%” align=”center”}