django-rest-swagger對API接口注釋
Swagger是一個API開發(fā)者的工具框架勺美，用于生成菩掏、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)遂填。總體目標(biāo)是使客戶端和文件系統(tǒng)服務(wù)器以同樣的速度來更新澈蝙，方法吓坚，參數(shù)和模型緊密集成到服務(wù)器端的代碼中，允許API始終保持同步灯荧。

在使用 django-rest-framework 進行API開發(fā)礁击，可以使用django-rest-swagger接入swagger自動生成接口文檔。

1. 安裝django-rest-swagger

pip install django-rest-swagger
2.配置settings.py

INSTALLED_APPS = [
    ...

    'rest_framework_swagger'

    ...
]

3. views.py

該博文的項目是django-rest-framework中文站點的例子：https://q1mi.github.io/Django-REST-framework-documentation

當(dāng)需要對接口的各種方法進行注釋時逗载，直接在該類下添加注釋哆窿，如下所示。需要注意是的：注釋的方法名稱（如 get厉斟、post）要對應(yīng)該類所含的方法名稱

class SnippetList(generics.ListCreateAPIView):
    """
    get:
        Return all snippets.
    post:
        Create a new snippet instance.
    """

    queryset = Snippet.objects.all()
    serializer_class = SnippetSerializer
    permission_classes = (permissions.IsAuthenticatedOrReadOnly,)

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)


class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
    """
    get:
        Return a snippet instance.
    put:
        Update a snippet instance.
    patch:
        Update a snippet instance.
    delete:
        Delete a snippet instance.
    """
    queryset = Snippet.objects.all()
    serializer_class = SnippetSerializer
    permission_classes = (permissions.IsAuthenticatedOrReadOnly, IsOwnerOrReadOnly,)


class UserList(generics.ListAPIView):
    """
    get:
        Return all users
    """
    queryset = MyUser.objects.all()
    serializer_class = UserSerializer


class UserDetail(generics.RetrieveAPIView):
    """
    get:
        Return a user instance
    """
    queryset = MyUser.objects.all()
    serializer_class = UserSerializer


class SnippetHighlight(generics.GenericAPIView):
    """
    get:
        Return a highlight instance
    """
    queryset = Snippet.objects.all()
    renderer_classes = (renderers.StaticHTMLRenderer,)

    def get(self, request, *args, **kwargs):
        snippet = self.get_object()
        return Response(snippet.highlighted)

3.配置urls.py

from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPICodec
schema_view = get_schema_view(title='API', renderer_classes=[SwaggerUIRenderer, OpenAPICodec])

urlpatterns = [
    
    ...

    url(r'docs/', schema_view, name='docs')

    ...
]

運行manage.py后挚躯，瀏覽器訪問 http://127.0.0.1:8000/，可以看到以下內(nèi)容：

image.png

訪問 http://127.0.0.1:8000/docs/擦秽，可以看到接口文檔如下：

image.png

點擊打開snippets码荔，可以看到如下，每個方法后面都有你在views.py中添加的注釋

image.png

點擊打開get方法感挥，如下