一、核心方案对比

方案	技术栈	优点	缺点
drf-yasg	Swagger 2.0	成熟稳定，支持Schema生成	不支持OpenAPI 3.0
drf-spectacular	OpenAPI 3.0	功能更强大，支持最新规范	部分旧项目兼容性需调整
手动编写	Markdown/HTML	完全定制化	维护成本高

---

二、方案一：drf-yasg（推荐）

1. 安装与配置

pip install drf-yasg

# settings.py
INSTALLED_APPS = [
    ...
    'drf_yasg',
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_yasg.inspectors.SwaggerAutoSchema',
}

2. 路由配置

# urls.py
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="API Docs",
        default_version='v1',
        description="API文档描述",
    ),
    public=True,
)

urlpatterns = [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='swagger'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='redoc'),
]

3. 接口注释规范

from drf_yasg.utils import swagger_auto_schema

class UserViewSet(ModelViewSet):
    @swagger_auto_schema(
        operation_description="获取用户列表",
        manual_parameters=[
            openapi.Parameter('role', openapi.IN_QUERY, description="角色筛选", type=openapi.TYPE_STRING),
        ],
        responses={200: UserSerializer(many=True)}
    )
    def list(self, request):
        # 业务逻辑

---

三、方案二：drf-spectacular（OpenAPI 3.0）

1. 安装配置

pip install drf-spectacular

# settings.py
INSTALLED_APPS = [
    ...
    'drf_spectacular',
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': 'My API',
    'DESCRIPTION': 'OpenAPI 3.0文档',
    'VERSION': '1.0.0',
}

2. 路由配置

# urls.py
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('schema/', SpectacularAPIView.as_view(), name='schema'),
    path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger'),
    path('redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

3. 高级注解

from drf_spectacular.utils import extend_schema

@extend_schema(
    description='创建新订单',
    request=OrderCreateSerializer,
    responses={201: OrderSerializer},
    methods=["POST"]
)
class OrderViewSet(ModelViewSet):
    # 业务逻辑

---

四、文档定制化技巧

1. 隐藏特定接口

# 在视图中设置
class InternalAPIView(APIView):
    @swagger_auto_schema(auto_schema=None)  # drf-yasg
    def post(self, request):
        ...

# 或全局过滤
SPECTACULAR_SETTINGS = {
    'EXCLUDE_PATH': [r'^api/internal/'],  # drf-spectacular
}

2. 添加JWT认证说明

# drf-yasg示例
schema_view = get_schema_view(
    ...
    security=[{'Bearer': []}],
    security_definitions={
        'Bearer': {
            'type': 'apiKey',
            'name': 'Authorization',
            'in': 'header'
        }
    }
)

---

五、部署与安全

1. 生产环境配置

# 仅允许认证用户访问文档
urlpatterns = [
    path('swagger/', login_required(schema_view.with_ui('swagger')), name='swagger'),
]

# 或使用Nginx限制IP访问
location /api/docs/ {
    allow 192.168.1.0/24;
    deny all;
}

2. 文档缓存优化

SPECTACULAR_SETTINGS = {
    'SERVE_INCLUDE_SCHEMA': False,  # 禁用Schema下载端点
    'PREPROCESSING_HOOKS': ['myapp.docs.hooks.preprocess_example'],
}

---

六、自动化流程集成

1. CI/CD集成

# GitHub Actions示例
jobs:
  generate_docs:
    runs-on: ubuntu-latest
    steps:
      - name: Generate OpenAPI schema
        run: |
          python manage.py spectacular --file schema.yml
      - name: Upload Artifact
        uses: actions/upload-artifact@v2
        with:
          name: api-schema
          path: schema.yml

2. 前端对接工具

• Postman：导入 schema.yml 自动生成测试集合
• Insomnia：通过 OpenAPI 插件同步接口定义

---

七、常见问题解决

1. 文档页面无法访问

• 检查 urls.py 路由配置是否正确
• 确认 settings.py 中已添加文档APP
• 查看浏览器控制台是否有CORS错误

2. 接口未显示在文档中

• 确认视图是否继承自 APIView 或 ViewSet
• 检查是否使用了 @swagger_auto_schema 或 @extend_schema 注解
• 验证 exclude_from_schema=True 是否被误用

---

通过以上方案，可快速生成专业级API文档并保持与代码同步更新。建议根据项目需求选择：

• 快速接入 → drf-yasg
• 最新规范支持 → drf-spectacular