安裝drf_spectacular

文檔

pypi鏈接:https://pypi.org/project/drf-spectacular/

文檔鏈接:https://drf-spectacular.readthedocs.io/en/latest/readme.html

安裝步驟

1. 在環境中添加

pip install drf-spectacular

2. 在setting的INSTALLED_APPS中添加

INSTALLED_APPS = [# ALL YOUR APPS'drf_spectacular',
]

3. 在setting的REST_FRAMEWORK中添加

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

4. 根據實機情況填寫setting中的SPECTACULAR_SETTINGS,此內容為添加

SPECTACULAR_SETTINGS = {"TITLE": "Your API","DESCRIPTION": "API documentation","VERSION": "1.0.0",# "SERVE_INCLUDE_SCHEMA": True,"SWAGGER_UI_DIST": "/static/swagger-ui-dist/",  # 本地靜態文件路徑"SWAGGER_UI_FAVICON_HREF": "/static/swagger-ui-dist/favicon-32x32.png",  # 本地圖標路徑"REDOC_DIST": "redoc-dist",  # 如果需要 Redoc
}

5. 在url.py文件中添加

urlpatterns = [# YOUR PATTERNSpath('api/schema/', SpectacularAPIView.as_view(), name='schema'),# Optional UI:path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

解決UI在線無法使用的問題

下載https://github.com/swagger-api/swagger-ui中的release內容

并根據第四步中的SWAGGER_UI_DIST內容,把release的dist內容放到具體的路徑上.

---

對接口進行說明

先展示一個實例

class UserViewSets(viewsets.ModelViewSet):queryset = user.objects.all()serializer_class = UserSerializersfilter_backends = [DjangoFilterBackend, OrderingFilter]ordering_fields = ["id"]filterset_fields = ["first_name"]# /user/search/?username=xxx# /user/search/?first_name=xxx@extend_schema(description="根據工號或者姓名查找用戶",parameters=[OpenApiParameter(name="username",description="員工工號",required=False,type=OpenApiTypes.STR,location=OpenApiParameter.QUERY,default="358256",examples=[OpenApiExample(name="第一頁", value=1, description="獲取第一頁數據"),OpenApiExample(name="第五頁", value=5, description="獲取第五頁數據"),],),OpenApiParameter(name="first_name",description="員工姓名",required=False,type=OpenApiTypes.STR,location=OpenApiParameter.QUERY,default="謝斯",),],summary="用戶詳情接口",)@action(detail=False, methods=["get"], url_path="search")def search(self, request):username = request.query_params.get("username", None)first_name = request.query_params.get("first_name", None)queryset = self.get_queryset()if username:queryset = queryset.filter(username=username)if first_name:queryset = queryset.filter(first_name=first_name)serializer = self.get_serializer(queryset, many=True)return Response(serializer.data)

需要注意的點

在view.py文件中需要引入對應的內容

from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiTypes, OpenApiExample

---

介紹SPECTACULAR_SETTINGS

配置項	類型	默認值	描述
基礎配置
TITLE	str	“API”	API 文檔的標題。
DESCRIPTION	str	“”	API 文檔的描述（Markdown 支持）。
VERSION	str	“1.0.0”	API 的版本號。
SERVE_URLCONF	str	當前 urls.py	定義用于生成文檔的 URL 配置。
SERVE_PATH	str	“/schema/”	OpenAPI Schema 的訪問路徑。
SERVE_INCLUDE_SCHEMA	bool	True	是否在 Swagger 頁面中顯示 Schema 鏈接。
接口過濾與路徑匹配
配置項 類型 默認值 描述
SCHEMA_PATH_PREFIX	str	r"^api/"	匹配生成文檔的 URL 路徑（正則表達式）。
SCHEMA_PATH_PREFIX_TRIM	bool	False	是否移除路徑前綴（如 /api/）以簡化文檔路徑。
SCHEMA_COERCE_PATH_PK	bool	False	將路徑中的 pk 強制轉換為整數類型。
SCHEMA_URL_PREFIX	str	“”	為所有接口路徑添加前綴（如 /v1/）。
認證與安全策略
AUTHENTICATION_CLASSES	list	項目默認的 REST_FRAMEWORK.AUTHENTICATION_CLASSES	指定需要包含在文檔中的認證類（如 JWT, Token）。
SECURITY_DEFINITIONS	dict	{}	定義安全策略（如 OAuth2、JWT）。
SECURITY_REQUIREMENTS	list	[]	指定默認的安全要求（如 [“BearerAuth”]）。
組件與擴展
COMPONENT_SPLIT_REQUEST	bool	False	是否將請求和響應拆分為獨立的組件（適用于復雜場景）。
ENUM_NAME_OVERRIDES	dict	{}	覆蓋枚舉字段的名稱（如 ChoiceField）。
TAGS	list	從視圖中自動提取	手動定義接口標簽（分組）。
PREPROCESSING_HOOKS	list	[]	在生成 Schema 前自定義處理函數（如修改參數）。
POSTPROCESSING_HOOKS	list	[]	在生成 Schema 后自定義處理函數（如添加注釋）。
UI 顯示優化
SWAGGER_UI_SETTINGS	dict	{}	自定義 Swagger UI 的行為（如主題、操作排序）。
REDOC_SETTINGS	dict	{}	自定義 ReDoc 的行為（如樣式、操作排序）。
SERVE_PUBLIC	bool	True	是否允許匿名用戶訪問文檔頁面。
高級配置
APPEND_COMPONENTS	dict	{}	手動添加 OpenAPI 組件（如自定義請求體格式）。
POSTPROCESSING_FILTER	callable	None	對生成的 Schema 進行過濾或修改。
EXTENSIONS	dict	{}	注冊自定義擴展（如支持 GraphQL）。