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‘...
]REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ('rest_framework.authentication.TokenAuthentication',),'DEFAULT_SCHEMA_CLASS':'rest_framework.schemas.AutoSchema','DEFAULT_PARSER_CLASSES': ['rest_framework.parsers.FormParser','rest_framework.parsers.MultiPartParser','rest_framework.parsers.JSONParser',]
}

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 = SnippetSerializerpermission_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 = SnippetSerializerpermission_classes = (permissions.IsAuthenticatedOrReadOnly, IsOwnerOrReadOnly,)class UserList(generics.ListAPIView):"""get:Return all users"""queryset = MyUser.objects.all()serializer_class = UserSerializerclass UserDetail(generics.RetrieveAPIView):"""get:Return a user instance"""queryset = MyUser.objects.all()serializer_class = UserSerializerclass 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)

在使用ModelViewSet时，用get/post/patch/会存在问题

所以需要看其django-restful源码，找到方法名：

class QR_result_table_ViewSet(viewsets.ModelViewSet):"""retrieve: Update a snippet instance.update:Update a snippet instance.partial_update:partial_update a snippet instance.destroy:Delete a snippet instance."""queryset = QR_result_table.objects.all()serializer_class = QR_result_table_Serializerpagination_class = ListPaginationfilter_backends = (filters.DjangoFilterBackend,)filter_class = QR_result_table_Filter

 

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/，可以看到以下內容：

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

 

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

 

點擊打開get方法，如下