寻求适配Django 2与DRF3.7.3的自描述API文档方案

Hey there! Let me walk you through some solid options that fit your Django 2 + DRF 3.7.3 setup and your need for API docs with clear request/response examples.

This tool has great compatibility with DRF 3.7.3, and it automatically generates Swagger/OpenAPI docs from your view docstrings, serializer metadata, and even lets you customize request/response examples exactly like you want.

• Installation: Grab a version that works with your DRF setup:

  pip install drf-yasg==1.17.1
  

• Basic Setup:
  1. Add 'drf_yasg' to your INSTALLED_APPS in settings.py
  2. Hook up the Swagger UI routes in urls.py:

     from drf_yasg.views import get_schema_view
     from drf_yasg import openapi
     from rest_framework import permissions
     
     schema_view = get_schema_view(
        openapi.Info(
           title="Your API Title",
           default_version='v1',
           description="Your API's detailed description",
        ),
        public=True,
        permission_classes=(permissions.AllowAny,),
     )
     
     urlpatterns = [
         # ... your existing routes
         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'),
     ]
     

• Adding Custom Examples: You can either use docstring annotations or the @swagger_auto_schema decorator to define examples. Here's how to replicate your desired output:

  from drf_yasg.utils import swagger_auto_schema
  from drf_yasg import openapi
  from rest_framework.views import APIView
  from rest_framework.response import Response
  
  class TestListView(APIView):
      """
      Retrieve a list of test entries
      """
      @swagger_auto_schema(
          responses={
              200: openapi.Response(
                  description="测试列表",
                  examples={
                      "application/json": [
                          {"name": "test1"},
                          {"name": "test2"}
                      ]
                  }
              )
          }
      )
      def get(self, request):
          # Your view logic here
          tests = [{"name": "test1"}, {"name": "test2"}]
          return Response(tests)
  

  The Swagger UI will display your exact example request/response, plus clear status code explanations.

If drf-yasg doesn't click with you, the 2.2.0 version of Django REST Swagger works well with DRF 3.7.3.

• Installation:

  pip install django-rest-swagger==2.2.0
  

• Setup:
  1. Add 'rest_framework_swagger' to INSTALLED_APPS
  2. Add the docs route to urls.py:

     from rest_framework_swagger.views import get_swagger_view
     
     schema_view = get_swagger_view(title='Your API Title')
     
     urlpatterns = [
         path('docs/', schema_view),
     ]
     

• Adding Examples: You can embed examples directly in your view's docstring using Markdown:

  class TestListView(APIView):
      """
      GET /tests
  
      **示例请求:**
      `GET /tests HTTP/1.1`
  
      **示例响应:**
      `HTTP/1.1 200 OK`
      `Content-Type: application/json`
  
      ```json
      [
        {"name": "test1"},
        {"name": "test2"}
      ]
      ```
  
      **状态码:**
      - 200 OK – 测试列表
      """
      def get(self, request):
          # Your view logic here
          pass
  

If all else fails, Sphinx can generate polished docs with your examples. You'll need the sphinxcontrib-restapi extension to integrate DRF-specific details.

• Steps:

  1. Install dependencies:

     pip install sphinx sphinxcontrib-restapi
     

  2. Initialize a Sphinx project with sphinx-quickstart

  3. Add 'sphinxcontrib.restapi' to the extensions list in conf.py

  4. Write your docs in .rst files (or use sphinx-apidoc to auto-generate view docs, then tweak them):

     Test List API
     =============
     
     **示例请求:**
     > GET /tests HTTP/1.1
     
     **示例响应:**
     > HTTP/1.1 200 OK
     > Content-Type: application/json
     
     ```json
     [
       {"name": "test1"},
       {"name": "test2"}
     ]
     

     状态码:

     • 200 OK – 测试列表

  5. Build the HTML docs with make html

内容的提问来源于stack exchange，提问作者user3608184