djangoswagger的全面介紹

Django是一個常用的Python Web框架，而djangoswagger，作為Django的一部分，是一個將Django Rest framework（DRF）API自動生成為Swagger UI和模型類文檔的工具，使得API文檔化更加方便並可視化。在本文中，我們將分別從以下幾個方面詳細介紹djangoswagger的特點和用法。

一、安裝和配置

安裝djangoswagger可以使用pip命令：

pip install django-rest-swagger

緊接著，在你的DRF配置類文件中添加以下應用配置：

INSTALLED_APPS = [
    ...,
    'rest_framework_swagger',
]

啟用REST framework的API文檔格式化器：

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
        'rest_framework_swagger.renderers.OpenAPIRenderer',
        'rest_framework_swagger.renderers.SwaggerUIRenderer',
    )
}

這樣，你的djangoswagger配置就完成了。

二、使用swagger UI

djangoswagger的核心是Swagger UI，它可以方便地展示API文檔的結構和參數。對於使用djangoswagger來說，想要在瀏覽器中顯示Swagger UI很簡單：

首先在你的Django項目的urls.py文件中添加以下代碼段，注意需要導入urls，schema_view和get_swagger_view的聲明：

from django.urls import path
from rest_framework_swagger.views import get_swagger_view
from rest_framework_schemas import get_schema_view

schema_view = get_swagger_view(title='API Documents')
urlpatterns = [
    ...,
    path('api-docs/', schema_view),
]

然後，訪問 ‘/api-docs/’ URL，就能看到你的API文檔了。

三、編寫API信息和參數

編寫API信息和參數是djangoswagger的一個重要功能，同時也是開發者最需要關注的部分。通過在你的DRF視圖類中添加djangoswagger的註解，API文檔就能自動生成：

from rest_framework.decorators import api_view, authentication_classes, permission_classes, renderer_classes
from rest_framework.response import Response
from rest_framework.renderers import JSONRenderer
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
from rest_framework_swagger import renderers
from rest_framework.authentication import BasicAuthentication
from rest_framework.permissions import IsAuthenticated

@api_view(['POST'])
@authentication_classes([BasicAuthentication])
@permission_classes([IsAuthenticated])
@renderer_classes([JSONRenderer, OpenAPIRenderer, SwaggerUIRenderer])
def my_view(request):
    """
    API 介面文檔描述
    ---
    請求參數:
        - a: integer // 描述參數1
        - b: string  // 描述參數2
    返回參數：
        - id: integer //返回參數1
        - name: string //返回參數1
    """
    return Response({'message': 'Hello, Django Swagger!'})

通過上述代碼我們完成了一個簡單的API介面，能夠將輸入參數a、b返回並輸出到介面中。其中註解中的描述信息更加直觀地體現了API介面的輸入輸出參數與詳細介紹。djangoswagger能夠解析上述註解中的格式，從而自動展示在Swagger UI的API 「操作」頁面中，方便開發者查看。

四、使用Markdown格式

Swagger UI支持使用Markdown格式，讓你不必受限於註解語法的規範，更加自由地書寫API介面的詳細介紹和示例代碼。你可以在註解中標註Markdown格式字元串，以實現多樣化的文本效果。

例如，介面簡要介紹中我們用到了控制標籤的方式，以實現更加清晰的顯示效果：

@api_view(['POST'])
@renderer_classes([JSONRenderer, OpenAPIRenderer, SwaggerUIRenderer])
def hello(request):
    """
    ### 訪問介面：/Hello/

    * **功能**

        獲取Hello信息，主要用於測試訪問介面是否正常。

    * **請求參數**

        無

    * **返回參數**

        - `Hello` : string ，返回基本信息

    """
    return Response({'Hello': 'Hello，Django Swagger!'})

五、在方法級別上定義標籤

默認情況下，Django Swagger會使用基於視圖類的路由實例的支持，自動檢測API介面的操作。如果你想在方法級別上定義標籤、描述信息等元數據，djangoswagger也允許你這麼做：

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    method='post',
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        required=['username', 'password'],
        properties={
            'username': openapi.Schema(type=openapi.TYPE_STRING, description='用戶名'),
            'password': openapi.Schema(type=openapi.TYPE_STRING, description='密碼')
        }),
    operation_description="註冊填寫信息"
)
@api_view(['POST'])
def register(request):
    """
    註冊
    """
    serializer = UserSerializer(data=request.DATA)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    else:
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

在上述代碼中我們添加了一個名叫register的API方法，給它添加了一些元數據，如參數詳細介紹、請求方式等。

六、結尾

Django Swagger作為Django的擴展在API文檔自動生成方面發揮了很大的作用，使得API文檔的編寫變得更加靈活和便捷。通過學習本文的介紹和代碼示例，我們相信讀者能夠掌握Django Swagger的主要用法並對介面文檔的設計有更深入的了解。