快捷導(dǎo)航

django-rest-swagger對(duì)API接口注釋的方法

更新時(shí)間：2019年08月29日 10:33:37 作者：傲嬌的草履蟲(chóng)

今天小編就為大家分享一篇django-rest-swagger對(duì)API接口注釋的方法，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。一起跟隨小編過(guò)來(lái)看看吧

Swagger是一個(gè)API開(kāi)發(fā)者的工具框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。總體目標(biāo)是使客戶端和文件系統(tǒng)服務(wù)器以同樣的速度來(lái)更新，方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼中，允許API始終保持同步。

在使用 django-rest-framework 進(jìn)行API開(kāi)發(fā)，可以使用django-rest-swagger接入swagger自動(dòng)生成接口文檔。

1. 安裝django-rest-swagger

pip install django-rest-swagger

2.配置settings.py

INSTALLED_APPS = [
 ...

 'rest_framework_swagger'

 ...
]

3. views.py

該博文的項(xiàng)目是django-rest-framework中文站點(diǎn)的例子：https://q1mi.github.io/Django-REST-framework-documentation

當(dāng)需要對(duì)接口的各種方法進(jìn)行注釋時(shí)，直接在該類下添加注釋，如下所示。需要注意是的：注釋的方法名稱（如 get、post）要對(duì)應(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')

 ...
]

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