利用drf_yasg.openapi自动生成RESTfulAPI文档的简单示例

drf_yasg.openapi是基于Django Rest Framework（DRF）和OpenAPI规范的一个库，可用于自动生成RESTfulAPI文档。它提供了一个易于使用的API视图生成器，可以生成详细而全面的API文档。

在本文中，我将为您提供一个简单的示例来演示如何使用drf_yasg.openapi来自动生成RESTfulAPI文档，并提供一些常见的使用例子。

首先，我们需要安装drf-yasg库。您可以使用以下命令来安装它：

pip install drf-yasg

安装完成后，我们需要进行一些配置。首先，在您的Django项目的settings.py文件中，添加以下内容：

INSTALLED_APPS = [
    ...
    'django.contrib.staticfiles',  # 静态资源处理
    'drf_yasg',
    ...
]

STATIC_URL = '/static/'

接下来，我们需要创建一个名为swagger的urls.py文件，并添加以下内容：

from django.urls import path
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
   openapi.Info(
      title="API文档",
      default_version='v1',
      description="这是一个示例API文档",
      terms_of_service="https://www.example.com/policies/terms/",
      contact=openapi.Contact(email="contact@example.com"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
)

urlpatterns = [
   path('swagger(<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'),
]

现在，我们可以通过访问/swagger/来查看自动生成的API文档。

下面，我将为您提供一些常见的使用例子。

1. 添加API文档注释

在您的DRF视图函数或类视图中，您可以使用注释来指定API的描述信息，参数说明等。例如：

from drf_yasg import openapi

class ExampleView(APIView):
    """
    这是一个示例视图
    """
    @swagger_auto_schema(
        operation_description="这是一个示例GET接口",
        responses={200: openapi.Response('成功')}
    )
    def get(self, request):
        """
        这是一个示例GET接口
        """
        ...

2. 指定请求参数

您可以使用swagger_auto_schema装饰器来指定请求参数。例如，您可以使用@swagger_auto_schema(query_serializer=YourSerializer)来指定查询参数的序列化器。

@swagger_auto_schema(query_serializer=YourSerializer)
def get(self, request):
    """
    这是一个示例GET接口
    """
    ...

3. 指定响应体

您可以使用@swagger_auto_schema(responses={status_code: Response(serializer)})来指定响应体的序列化器。

@swagger_auto_schema(responses={200: YourSerializer})
def get(self, request):
    """
    这是一个示例GET接口
    """
    ...

4. 使用文章模块开发API文档

from drf_yasg.utils import swagger_auto_schema
from rest_framework import generics, permissions, serializers

from .models import Article
from .serializers import ArticleSerializer


class ArticleList(generics.ListCreateAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]

    @swagger_auto_schema(responses={200: ArticleSerializer(many=True)})
    def get(self, request, *args, **kwargs):
        return self.list(request, *args, **kwargs)

    @swagger_auto_schema(request_body=ArticleSerializer)
    def post(self, request, *args, **kwargs):
        return self.create(request, *args, **kwargs)


class ArticleDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    permission_classes = [permissions.IsOwnerOrReadOnly]

    @swagger_auto_schema(responses={200: ArticleSerializer()})
    def get(self, request, *args, **kwargs):
        return self.retrieve(request, *args, **kwargs)

    @swagger_auto_schema(request_body=ArticleSerializer)
    def put(self, request, *args, **kwargs):
        return self.update(request, *args, **kwargs)

    def delete(self, request, *args, **kwargs):
        return self.destroy(request, *args, **kwargs)

以上是使用drf_yasg.openapi自动生成RESTfulAPI文档的简单示例和使用例子。通过使用drf_yasg.openapi，我们可以轻松地生成全面且易于理解的API文档，从而提升API开发的效率和可维护性。