在Django 1.6项目中集成Swagger 0.3.x与DRF后，如何关联REST接口？

嘿，我之前也维护过类似的老旧Django项目，刚好熟悉这个版本组合的配置，给你梳理下具体操作：

1. 确保你的API视图遵循DRF规范 #

Swagger只会识别DRF官方定义的视图，所以先检查你的接口是否用了以下方式实现：

• 基于类的视图：继承rest_framework.views.APIView或者ViewSet系列类
• 函数视图：用rest_framework.decorators.api_view装饰器包裹

举个函数视图的例子：

from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(['GET'])
def user_list(request):
    # 你的业务逻辑
    return Response({"users": []})

2. 给视图添加Swagger可识别的文档注释 #

这个版本的DRF-Swagger依赖视图的文档字符串+Swagger特定格式注解来生成接口文档。你需要在文档字符串里用---分隔基础描述和Swagger参数/返回值定义：

@api_view(['GET'])
def user_list(request):
    """
    获取系统用户列表
    ---
    parameters:
      - name: page
        type: integer
        required: false
        description: 分页页码，默认值为1
      - name: page_size
        type: integer
        required: false
        description: 每页条数，默认值为10
    responses:
      200:
        description: 成功返回用户列表
        schema:
          type: object
          properties:
            count:
              type: integer
              description: 总用户数
            results:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  username:
                    type: string
                  email:
                    type: string
    """
    # 业务逻辑代码
    return Response(...)

对于类视图（比如APIView），你可以在类的方法（如get、post）里添加同样格式的文档字符串。

3. 配置Swagger的基础设置 #

在项目的settings.py里添加SWAGGER_SETTINGS配置，帮助Swagger定位和展示你的接口：

SWAGGER_SETTINGS = {
    # 不排除任何命名空间，确保所有DRF视图都被扫描
    "exclude_namespaces": [],
    # API版本号
    "api_version": '1.0',
    # API根路径
    "api_path": "/",
    # 允许展示的请求方法
    "enabled_methods": ['get', 'post', 'put', 'patch', 'delete'],
    # 文档页面的基础信息
    "info": {
        'title': '项目V1版本API文档',
        'description': '这里是项目所有REST接口的详细说明',
        'contact': 'dev-team@yourcompany.com',
    },
    # 如果你的API不需要认证，保持这两个为False
    "is_authenticated": False,
    "is_superuser": False,
}

4. 检查路由结构匹配 #

确保你的API路由和Swagger的URL前缀一致。比如你把Swagger挂载在/api/v1/下，那么你的接口路由也应该放在这个前缀下：

# 主urls.py
urlpatterns = [
    # Swagger路由
    url(r'^api/v1/$', include('rest_framework_swagger.urls')),
    # 你的API路由，必须在api/v1/前缀下
    url(r'^api/v1/users/', include('users.urls')),
    url(r'^api/v1/orders/', include('orders.urls')),
]

5. 验证效果 #

重启Django服务，刷新Swagger页面，你应该能看到所有符合DRF规范且添加了文档注释的接口了。如果某个接口没显示，优先检查：

• 是否用了DRF的视图类/装饰器
• 文档字符串的格式是否正确（尤其是---分隔符）
• 路由是否在Swagger的扫描范围内

内容的提问来源于stack exchange，提问作者Stan Reduta