超好用的API工具-Swagger

4,408 阅读3分钟

image

今天给大家介绍一个日常开发中用到的工具Swagger,swagger是一个RESTful文档生成工具。

官方描述是 「The Best APIs are Built with Swagger Tools」 很是霸气。

Swagger可以用在多个语言框架中,比如Python下面flask框架有「flask-restful-swagger」,Django框架「django-rest-swagger」,甚至tornado也有了只是使用量比起前两者少多了。

由于swagger功能强大,集成工具非常之多,今天我们主要了解swagger-ui。

为什么使用swagger-ui

程序界里面经常传这样一句话,程序员最讨厌的两件事:

1.写注释写文档 2.别人不写注释、不写文档。

为什么这样说?因为管理文档注释比较麻烦,经常会出现API更新了,文档还是老的,各种同步不一致的情况。造成很多问题,从而耽搁彼此的时间,所以大家不太喜欢进行写文档注释。

而之所以使用swagger主要是swagger它可以降低我们前后端开发文档同步问题,swagger可以从我们代码注释里面自动生成API文档,以此方便前端对接使用。

其次它可以展示我们所有接口列表情况,非常方便我们前后端进行接口调试。前端同学对接接口直接在页面就能操作了,完全不需要在postman,PAW这些网络工具进行切换,非常简单方便。

下面我来一个官方的预览图数据表定义:

image

Django swagger安装使用

接下来我们就来就来讲下安装使用过程,由于我们主要是Python为主,大家介绍swagger-ui,这里面我们简单Django为主介绍下使用:

pip install django-rest-swagger 要求: Django 1.8+ Django REST framework 3.5.1+ Python 2.7, 3.5, 3.6

在 INSTALLED_APPS

    INSTALLED_APPS = (
        ...        'rest_framework_swagger',
    )

添加文档地址:

from django.conf.urls import urlfrom rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='Pastebin API')

test_urlpatterns = [
    url(r'^$', schema_view)  # 这儿你自定义文档目录]#这里面我们需要注意这儿在本地或者测试环境使用,线上不能使用,最简单的办法就是我之前提到过的的,通过环境变量来进行判断当前环境从而是否加上这个test_urlpatterns。if current_env not in ['product', 'staging']:
    url_patterns = url_patterns + test_urlpatterns

最后得到的效果就是类似的效果:

image

如果配合Django-filter,会更加方便进行前端筛选测试,几乎是对于XXX管理页面就是举手之间。swagger配合Django-REST-Framework可以说大大提高了后端写增删查改(CRUD)并且对接完成的速度。

其他语言使用

swagger不仅Python使用,其他语言框架都能进行使用swagger。推荐大家去使用,不管是否是Python程序员。

其他语言工具集成的地址:https://swagger.io/tools/open-source/open-source-integrations/

image

不清楚还有多少公司,每次API更新了,文档没有更新,造成对接起来彼此不一致的情况,反正听到过身边的朋友反馈过。

如果你发现自己公司有这种情况,赶紧swagger一把梭。

上面就是我对swagger-ui的介绍,实际swagger tools 还有其他两个功能强大的工具 swagger-editor,swagger-codegen。大家感兴趣可以自己去了解。

image

相关文章:

容器化部署实践之Django应用部署(二)

使用Docker容器化部署实践之Django应用部署(一)

Python web开发从入门到放弃

编写高质量Python的6个技巧

Python新手常见的几个问题及工具推荐

image