1. 程式人生 > >django-rest-swagger對API接口註釋

django-rest-swagger對API接口註釋

port self. auth bubuko all 註意 image url sch

Swagger是一個API開發者的工具框架,用於生成、描述、調用和可視化RESTful風格的Web服務。總體目標是使客戶端和文件系統服務器以同樣的速度來更新,方法,參數和模型緊密集成到服務器端的代碼中,允許API始終保持同步。

在使用 django-rest-framework 進行API開發,可以使用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

當需要對接口的各種方法進行註釋時,直接在該類下添加註釋,如下所示。需要註意是的:註釋的方法名稱(如 get、post)要對應該類所含的方法名稱

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(rdocs/, schema_view, name=docs)

    ...
]

運行manage.py後,瀏覽器訪問 http://127.0.0.1:8000/,可以看到以下內容:

技術分享圖片

訪問 http://127.0.0.1:8000/docs/,可以看到接口文檔如下:

技術分享圖片

點擊打開snippets,可以看到如下,每個方法後面都有你在views.py中添加的註釋

技術分享圖片

點擊打開get方法,如下

技術分享圖片

django-rest-swagger對API接口註釋