pip install -U drf-yasg

INSTALLED_APPS = [
   # ...
   'django.contrib.staticfiles',  # 用于提供 Swagger UI 的靜態(tài)文件
   'drf_yasg',
   # ...
]

from django.urls import re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 配置 API 文檔基本信息
schema_view = get_schema_view(
   openapi.Info(
      title="項(xiàng)目 API",
      default_version='v1',
      description="API 接口文檔描述",
      terms_of_service="https://www.example.com/terms/",
      contact=openapi.Contact(email="contact@example.com"),
      license=openapi.License(name="MIT License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),  # 允許任何人訪問文檔
)

# 添加 URL 路由
urlpatterns = [
   # ...
   # 文檔 JSON/YAML 下載
   path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   # Swagger UI 頁面
   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   # ReDoc 頁面
   path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   # ...
]

pip install drf-spectacular
pip install drf-spectacular[sidecar] # 安裝內(nèi)置 UI 資源（推薦）

INSTALLED_APPS = [
	# ...
    'drf_spectacular',
    'drf_spectacular_sidecar',  # 內(nèi)置 UI 資源
    # ...
]

# 配置 DRF
REST_FRAMEWORK = {
    # OpenAPI 文檔
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

### drf-spectacular OpenAPI 文檔配置
SPECTACULAR_SETTINGS = {
    "SWAGGER_UI_DIST": "SIDECAR",  # 使用內(nèi)置 UI
    "SWAGGER_UI_FAVICON_HREF": "SIDECAR",
    "TITLE": "MarsMgn API",
    "DESCRIPTION": "火星信息平臺(tái)接口文檔",
    "VERSION": "1.0.0",
    "SERVE_INCLUDE_SCHEMA": False,  # 不在文檔中包含 schema 本身
}

from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView

urlpatterns = [
    #...
    # API schema 生成端點(diǎn)
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Swagger UI 界面
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    # ReDoc 界面
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
    #...
]

class SystemPost(models.Model):
    id = models.BigAutoField(primary_key=True, help_text="崗位ID")
    code = models.CharField(
        max_length=64,
        help_text="崗位編碼",  # 會(huì)顯示在文檔中
    )

from drf_spectacular.utils import extend_schema

@extend_schema(summary="創(chuàng)建崗位", description="自定義接口詳細(xì)說明")
@action(methods=["post"], detail=False, url_path="create")
def create_post(self, request, *args, **kwargs):
    return self.custom_create(request, *args, **kwargs)

@extend_schema(tags=["管理后臺(tái)-system-崗位"])
class PostViewSet(CustomViewSet):
    queryset = SystemPost.objects.all()
    filterset_class = SystemPostFilter

from drf_spectacular.utils import extend_schema, OpenApiResponse
from drf_spectacular.types import OpenApiTypes

@extend_schema(
    responses={
        200: OpenApiResponse(
            description="操作成功",
            response={
                "type": "object",
                "properties": {
                    "code": {"type": "integer", "example": 0},
                    "data": {"type": "boolean", "example": True},
                    "msg": {"type": "string", "example": ""}
                }
            }
        )
    }
)
def delete_post(self, request, *args, ?**kwargs):
    """刪除崗位"""
    return Response({"code": 0, "data": True, "msg": ""}, status=200)