Step15: 自动生成接口文档

Author: yangxg

.idea/HelloDjango-rest-framework-tutorial.iml

@@ -20,6 +20,7 @@ django-filter = "*"
 drf-haystack = "*"
 drf-extensions = "*"
 django-redis-cache = "*"
+drf-yasg = "*"
 
 [requires]
 python_version = "3"

.idea/codeStyles/codeStyleConfig.xml

@@ -197,12 +197,13 @@ $ git clone https://github.com/HelloGitHub-Team/HelloDjango-REST-framework-tutor
 8. [文章详情 API](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/97/)
 9. [在接口返回Markdown解析后的内容](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/98/)
 10. [实现分类、标签、归档日期接口](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/99/)
-11. [评论接口](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/100/))
-12. [基于 drf-haystack 实现文章搜索接口](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/101/))
-13. [加缓存为接口提速](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/102/))
-14. [API 版本管理](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/103/))
-15. [限制接口访问频率](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/104/))
-16. [单元测试](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/105/))
+11. [评论接口](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/100/)
+12. [基于 drf-haystack 实现文章搜索接口](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/101/)
+13. [加缓存为接口提速](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/102/)
+14. [API 版本管理](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/103/)
+15. [限制接口访问频率](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/104/)
+16. [单元测试](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/105/)
+17. [自动生成接口文档](https://www.zmrenwu.com/courses/django-rest-framework-tutorial/materials/106/)
 
 ## 公众号
 <p align="center">

.idea/misc.xml

@@ -1,14 +1,22 @@
 from django_filters import rest_framework as drf_filters
 
-from .models import Post
+from .models import Category, Post, Tag
 
 
 class PostFilter(drf_filters.FilterSet):
     created_year = drf_filters.NumberFilter(
-        field_name="created_time", lookup_expr="year"
+        field_name="created_time", lookup_expr="year", help_text="根据文章发表年份过滤文章列表。"
     )
     created_month = drf_filters.NumberFilter(
-        field_name="created_time", lookup_expr="month"
+        field_name="created_time", lookup_expr="month", help_text="根据文章发表月份过滤文章列表。"
+    )
+    category = drf_filters.ModelChoiceFilter(
+        queryset=Category.objects.all(),
+        help_text="根据分类过滤文章列表。",
+    )
+    tags = drf_filters.ModelMultipleChoiceFilter(
+        queryset=Tag.objects.all(),
+        help_text="根据标签过滤文章列表。",
     )
 
     class Meta:

Pipfile

@@ -1,9 +1,8 @@
 from django.contrib.auth.models import User
+from drf_haystack.serializers import HaystackSerializerMixin
 from rest_framework import serializers
 from rest_framework.fields import CharField
 
-from drf_haystack.serializers import HaystackSerializerMixin
-
 from .models import Category, Post, Tag
 from .utils import Highlighter
 
@@ -56,8 +55,10 @@ class PostRetrieveSerializer(serializers.ModelSerializer):
     category = CategorySerializer()
     author = UserSerializer()
     tags = TagSerializer(many=True)
-    toc = serializers.CharField()
-    body_html = serializers.CharField()
+    toc = serializers.CharField(label="文章目录", help_text="HTML 格式，每个目录条目均由 li 标签包裹。")
+    body_html = serializers.CharField(
+        label="文章内容", help_text="HTML 格式，从 `body` 字段解析而来。"
+    )
 
     class Meta:
         model = Post
@@ -87,8 +88,14 @@ def to_representation(self, value):
 
 
 class PostHaystackSerializer(HaystackSerializerMixin, PostListSerializer):
-    title = HighlightedCharField()
-    summary = HighlightedCharField(source="body")
+    title = HighlightedCharField(
+        label="标题", help_text="标题中包含的关键词已由 HTML 标签包裹，并添加了 class，前端可设置相应的样式来高亮关键。"
+    )
+    summary = HighlightedCharField(
+        source="body",
+        label="摘要",
+        help_text="摘要中包含的关键词已由 HTML 标签包裹，并添加了 class，前端可设置相应的样式来高亮关键。",
+    )
 
     class Meta(PostListSerializer.Meta):
         search_fields = ["text"]

Pipfile.lock

@@ -1,6 +1,12 @@
 from django.shortcuts import get_object_or_404
+from django.utils.decorators import method_decorator
 from django.views.generic import DetailView, ListView
 from django_filters.rest_framework import DjangoFilterBackend
+from drf_haystack.viewsets import HaystackViewSet
+from drf_yasg import openapi
+from drf_yasg.inspectors import FilterInspector
+from drf_yasg.utils import swagger_auto_schema
+from pure_pagination.mixins import PaginationMixin
 from rest_framework import mixins, status, viewsets
 from rest_framework.decorators import action
 from rest_framework.generics import ListAPIView
@@ -10,26 +16,15 @@
 from rest_framework.serializers import DateField
 from rest_framework.throttling import AnonRateThrottle
 from rest_framework_extensions.cache.decorators import cache_response
-from rest_framework_extensions.key_constructor.bits import (
-    ListSqlQueryKeyBit,
-    PaginationKeyBit,
-    RetrieveSqlQueryKeyBit,
-)
+from rest_framework_extensions.key_constructor.bits import ListSqlQueryKeyBit, PaginationKeyBit, RetrieveSqlQueryKeyBit
 from rest_framework_extensions.key_constructor.constructors import DefaultKeyConstructor
 
 from comments.serializers import CommentSerializer
-from drf_haystack.viewsets import HaystackViewSet
-from pure_pagination.mixins import PaginationMixin
 
 from .filters import PostFilter
 from .models import Category, Post, Tag
 from .serializers import (
-    CategorySerializer,
-    PostHaystackSerializer,
-    PostListSerializer,
-    PostRetrieveSerializer,
-    TagSerializer,
-)
+    CategorySerializer, PostHaystackSerializer, PostListSerializer, PostRetrieveSerializer, TagSerializer)
 from .utils import UpdatedAtKeyBit
 
 
@@ -125,6 +120,22 @@ class IndexPostListAPIView(ListAPIView):
 class PostViewSet(
     mixins.ListModelMixin, mixins.RetrieveModelMixin, viewsets.GenericViewSet
 ):
+    """
+    博客文章视图集
+
+    list:
+    返回博客文章列表
+
+    retrieve:
+    返回博客文章详情
+
+    list_comments:
+    返回博客文章下的评论列表
+
+    list_archive_dates:
+    返回博客文章归档日期列表
+    """
+
     serializer_class = PostListSerializer
     queryset = Post.objects.all()
     permission_classes = [AllowAny]
@@ -148,8 +159,14 @@ def list(self, request, *args, **kwargs):
     def retrieve(self, request, *args, **kwargs):
         return super().retrieve(request, *args, **kwargs)
 
+    @swagger_auto_schema(responses={200: "归档日期列表，时间倒序排列。例如：['2020-08', '2020-06']。"})
     @action(
-        methods=["GET"], detail=False, url_path="archive/dates", url_name="archive-date"
+        methods=["GET"],
+        detail=False,
+        url_path="archive/dates",
+        url_name="archive-date",
+        filter_backends=None,
+        pagination_class=None,
     )
     def list_archive_dates(self, request, *args, **kwargs):
         dates = Post.objects.dates("created_time", "month", order="DESC")
@@ -163,6 +180,8 @@ def list_archive_dates(self, request, *args, **kwargs):
         detail=True,
         url_path="comments",
         url_name="comment",
+        filter_backends=None,  # 移除从 PostViewSet 自动继承的 filter_backends，这样 drf-yasg 就不会生成过滤参数
+        suffix="List",  # 将这个 action 返回的结果标记为列表，否则 drf-yasg 会根据 detail=True 将结果误判为单个对象
         pagination_class=LimitOffsetPagination,
         serializer_class=CommentSerializer,
     )
@@ -183,6 +202,13 @@ def list_comments(self, request, *args, **kwargs):
 
 
 class CategoryViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    博客文章分类视图集
+
+    list:
+    返回博客文章分类列表
+    """
+
     serializer_class = CategorySerializer
     # 关闭分页
     pagination_class = None
@@ -192,6 +218,13 @@ def get_queryset(self):
 
 
 class TagViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    博客文章标签视图集
+
+    list:
+    返回博客文章标签列表
+    """
+
     serializer_class = TagSerializer
     # 关闭分页
     pagination_class = None
@@ -204,15 +237,53 @@ class PostSearchAnonRateThrottle(AnonRateThrottle):
     THROTTLE_RATES = {"anon": "5/min"}
 
 
+class PostSearchFilterInspector(FilterInspector):
+    def get_filter_parameters(self, filter_backend):
+        return [
+            openapi.Parameter(
+                name="text",
+                in_=openapi.IN_QUERY,
+                required=True,
+                description="搜索关键词",
+                type=openapi.TYPE_STRING,
+            )
+        ]
+
+
+@method_decorator(
+    name="retrieve",
+    decorator=swagger_auto_schema(
+        auto_schema=None,
+    ),
+)
+# @method_decorator(
+#     name="list",
+#     decorator=swagger_auto_schema(
+#         operation_description="返回关键词搜索结果",
+#         filter_inspectors=[PostSearchFilterInspector],
+#     ),
+# )
 class PostSearchView(HaystackViewSet):
+    """
+    搜索视图集
+
+    list:
+    返回搜索结果列表
+    """
+
     index_models = [Post]
     serializer_class = PostHaystackSerializer
     throttle_classes = [PostSearchAnonRateThrottle]
 
 
 class ApiVersionTestViewSet(viewsets.ViewSet):  # pragma: no cover
+    swagger_schema = None
+
     @action(
-        methods=["GET"], detail=False, url_path="test", url_name="test",
+        methods=["GET"],
+        detail=False,
+        url_path="test",
+        url_name="test",
     )
     def test(self, request, *args, **kwargs):
         if request.version == "v1":

README.md

@@ -31,6 +31,7 @@
     "django.contrib.staticfiles",
     "pure_pagination",  # 分页
     "haystack",  # 搜索
+    "drf_yasg",  # 文档
     "rest_framework",
     "django_filters",
     "blog.apps.BlogConfig",  # 注册 blog 应用

blog/filters.py

@@ -14,8 +14,10 @@
     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
 """
 from django.contrib import admin
-from django.urls import include, path
-from rest_framework import routers
+from django.urls import include, path, re_path
+from drf_yasg import openapi
+from drf_yasg.views import get_schema_view
+from rest_framework import permissions, routers
 
 import blog.views
 import comments.views
@@ -32,6 +34,19 @@
     r"api-version", blog.views.ApiVersionTestViewSet, basename="api-version"
 )
 
+schema_view = get_schema_view(
+    openapi.Info(
+        title="HelloDjango REST framework tutorial API",
+        default_version="v1",
+        description="HelloDjango REST framework tutorial AP",
+        terms_of_service="",
+        contact=openapi.Contact(email="zmrenwu@163.com"),
+        license=openapi.License(name="GPLv3 License"),
+    ),
+    public=True,
+    permission_classes=(permissions.AllowAny,),
+)
+
 urlpatterns = [
     path("admin/", admin.site.urls),
     path("search/", include("haystack.urls")),
@@ -42,4 +57,16 @@
     path("api/v1/", include((router.urls, "api"), namespace="v1")),
     path("api/v2/", include((router.urls, "api"), namespace="v2")),
     path("api/auth/", include("rest_framework.urls", namespace="rest_framework")),
+    # 文档
+    re_path(
+        r"swagger(?P<format>\.json|\.yaml)",
+        schema_view.without_ui(cache_timeout=0),
+        name="schema-json",
+    ),
+    path(
+        "swagger/",
+        schema_view.with_ui("swagger", cache_timeout=0),
+        name="schema-swagger-ui",
+    ),
+    path("redoc/", schema_view.with_ui("redoc", cache_timeout=0), name="schema-redoc"),
 ]

blog/serializers.py

@@ -53,6 +53,13 @@ def comment(request, post_pk):
 
 
 class CommentViewSet(mixins.CreateModelMixin, viewsets.GenericViewSet):
+    """
+    博客评论视图集
+
+    create:
+    创建博客评论
+    """
+
     serializer_class = CommentSerializer
 
     def get_queryset(self):  # pragma: no cover