5分钟了解swagger

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。

前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。

没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。

书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。 在此先介绍一款其他的API文档工具,叫rap,这玩意儿用一句话就能概括:解放生产力,代替手写API的web工具。

RAP写起来确实比手写文档要快,看看图就知道:

可以选择某个项目,写针对某个项目的API

请看,可以填写请求和相应的字段

还可以选择字段对应的类型

类似的API文档工具网上还有很多,但是能拿上台面的,不多。RAP是由阿里开发的,整个阿里都在用,还不错。

github地址为:https://github.com/thx/RAP

当然咯,rap不可能只有线上版本,肯定可以部署到私服上。

https://github.com/thx/RAP/wiki/deploy_manual_cn

swagger

rap挺好的,但是和swagger比起来有点轻量。

先看看swagger的生态使用图:

其中,红颜色的是swaggger官网方推荐的。

下面再细看看swagger的生态的具体内容:

swagger-ui

这玩意儿从名字就能看出来,用来显示API文档的。和rap不同的是,它不可以编辑。

点击某个详细API的可以试。

swagger-editor

就是一个在线编辑文档说明文件(swagger.json或swagger.yaml文件)的工具,以方便生态中的其他小工具(swagger-ui)等使用。

左边编辑,右边立马就显示出编辑内容来。

编辑swagger说明文件使用的是yaml语法具体的内容可以去官网查看。 各种语言版本的根据annotation或者注释生成swagger说明文档的工具

目前最流行的做法,就是在代码注释中写上swagger相关的注释,然后,利用小工具生成swagger.json或者swagger.yaml文件。 目前官方没有推出。github上各种语言各种框架各种有,可以自己搜吧搜吧,这里只说一个php相关的。

swagger-php :https://github.com/zircote/swagger-php

swagger-validator

这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单,只需url地址栏,根路径下加上一个参数url,参数内容是放swagger说明文件的地址。即可校验。

例如:

docker hub地址为:https://hub.docker.com/r/swaggerapi/swagger-validator/

可以pull下镜像来自己玩玩。

swagger-codegen

代码生成器,脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。

有一定用处,Java系用的挺多。工业上应该不咋用。

mock server

这个目前还没有找到很合适的mock工具,包括rap也好,其他API文档工具也好,都做的不够完善,大多就是根据说明文件,例如swagger.json等生成一些死的静态的mock数据,不能够根据限定条件:例如“只能是数字,必传”等做出合理的回应。

原文发布于微信公众号 - 互扯程序(chat_routine)

原文发表时间:2018-10-15

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏搜云库

分布式和集群区别?什么是云计算平台?分布式的应用场景?

分布式是指将一个业务拆分不同的子业务,分布在不同的机器上执行,集群是指多台服务器集中在一起,实现同一业务,可以视为一台计算机,一个云计算平台,就是通过一套软件系...

93410
来自专栏Python与爬虫

爬虫入门到精通-开始爬虫之旅

本文章属于爬虫入门到精通系统教程第一讲 什么是爬虫? 引用自维基百科 网络蜘蛛(Web spider)也叫网络爬虫(Web crawler),蚂蚁(ant),...

3478
来自专栏BestSDK

一款完美的SDK产品,肯定具备这9个特质

即保证用户能够在5分钟以内学会使用代码。这一点非常重要,特别是考虑到有时候用户会评估我们的产品——如果无法轻松上手,他们很可能直接选择放弃。 ? 1. 简单性 ...

43810
来自专栏纯洁的微笑

[高级]关于分布式事务、两阶段提交协议、三阶提交协议

在分布式系统中,为了保证数据的高可用,通常,我们会将数据保留多个副本(replica),这些副本会放置在不同的物理的机器上。为了对用户提供正确的增\删\改\差等...

1123
来自专栏進无尽的文章

聊聊工程级别的组件化、插件化 以及 模块化

我们经常会听到组件化、插件化、模块化这三个概念,可是我们真的对这三个概念了解吗?明白它们三者之前的关系和区别吗?本文就我个人的理解做一下简单的总结,如有错误之处...

3974
来自专栏跨界架构师

做了「负载均衡」就可以随便加机器了吗?这三招来帮你!

        这篇是《分布式关注点系列》中「负载均衡」相关的内容最后一发了,后续也会继续讲「高可用」相关的其它主题,主要是限流、降级、熔断之类的吧,具体还没定...

1325
来自专栏散尽浮华

网站系统架构梳理-解决高负载高并发

随着互联网业务的不断丰富,网站系统架构已经细分到方方面面,尤其对于大型网站来说,所采用的技术更是涉及面非常广,从硬件到软件、编程语言、数据库、WebServer...

42910
来自专栏携程技术中心

开源 | 携程Redis多数据中心解决方案-XPipe

作者简介 孟文超,携程技术中心框架研发部高级经理。2016年加入携程,目前主要负责Redis多数据中心项目XPipe。此前曾在大众点评工作,任基础架构部门通信团...

53710
来自专栏张善友的专栏

K2 Blackpearl的Outcomes Actions和Line Rule

使用K2 blackpearl设计流程的时候有两个重要概念是Outcomes和Actions。 ? Actions代表的是人与工作流交互的时候,对流程处理的...

1897
来自专栏非著名程序员

如何用好 GitHub 中的 Watch、Star、Fork

在每个 github 项目的右上角,都有三个按钮,分别是 watch、star、fork,但是有些刚开始使用 github 的同学,可能对这三个按钮的使用却不怎...

33410

扫码关注云+社区

领取腾讯云代金券