django rest swagger

时间主题

11.21（周四）20:00 契约测试&Swagger

在周四的测试运维试听课程中，芒果给大家介绍了契约测试，以及基于django rest framework 的 Swagger使用，这里我们来做个小总结。

什么是契约测试契约测试，又称之为消费者驱动的契约测试(Consumer-Driven Contracts Test，简称CDCT)，根据 消费者驱动契约 ，我们可以将服务分为消费者端和生产者端，而消费者驱动的契约测试的核心思想在于是从消费者业务实现的角度出发，由消费者自己会定义需要的数据格式以及交互细节，并驱动生成一份契约文件。然后生产者根据契约文件来实现自己的逻辑，并在持续集成环境中持续验证。在我们前面的文章中有详细介绍：契约测试：解决微服务测试的问题

这里就不做再一次的重复，我们介绍一下另外一个契约测试工具Swagger。

Swagger介绍

Swagger跟前面《契约测试：解决微服务测试的问题》提到的Pact一样，是成熟的契约测试解决方案。

Swagger可以贯穿于整个API生态，如API的设计、编写API文档、测试和部署。它是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger的总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。当接口有变动时，对应的接口文档也会自动更新。

Swagger应用场景：

如果你的RESTful API接口都开发完成了，可以用Swagger-editor来编写API 文档（yaml文件或json文件），然后通过Swagger-ui来渲染该文件，展现API文档。

如果你的RESTful API还未开始，也可以使用Swagger生态，来设计和规范你的API，以Annotation（注解）的方式给你的源代码添加额外的元数据。这样Swagger就可以检测到这些元数据，自动生成对应的API描述信息。Swagger 支持自动生成 API 文档。

下面我们一起来看看基于Django rest API开发的rest framework Swagger的使用。

Django REST Swagger

在我们接口开发完之后，需要交付给别人对接，在没有使用swagger的时候，我们需要单独编写一份api接口文档，由postman之类的工具进行请求得到返回的结果。

而有了swagger之后，可以通过提取接口代码中的注释来生成文档，并且可以直接在浏览器中调用，获取返回结果。

Django REST Swagger安装：

pip install django-rest-swagger

Django REST Swagger配置：

在项目配置文件setting.py中添加：

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

REST_FRAMEWORK = { 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}然后在你的视图函数或者类里面添加好对应的注释：

class ScriptsView(generics.ListCreateAPIView): """ get: list all script instance post: create a script intance """ queryset = Script.objects.all() serializer_class = ScriptSerializers

class ScriptDetail(generics.RetrieveUpdateDestroyAPIView): """ get: get a script instance put: update a script intance patch: update a script intance delete: delete a script intance """ queryset = Script.objects.all()    serializer_class = ScriptSerializers最后设置显示urls.py文件中设置显示信息：

from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRendererfrom rest_framework.schemas import get_schema_view

schema_view = get_schema_view(title="MyWebSite API",renderer_classes=[SwaggerUIRenderer,OpenAPIRenderer])

urlpatterns = [ ..., path('docs/',schema_view)]效果图如下：

后续的啰啰嗦嗦当然除了课程内容除了这些基本的介绍，芒果还给大家介绍了，关于带大家学习 Python 的 web 项目的 RESTful API开发框架中CBV模式开发等内容。