写api接口神器－－带你5分钟了解swagger

随着互联网技术的发展，如今的网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，并且前端技术和后端技术在各自的道路上越走越远。 
前端和后端的惟一联系，变成了API接口；API文档变成了先后端开发人员联系的纽带，变得愈来愈重要，swagger就是一款让你更好的书写API文档的框架。

其余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数据，不可以根据限定条件：例如“只能是数字，必传”等作出合理的回应。

 

 

 

我的公众号谢谢各位老铁支持