随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 
前端和后端的唯一联系,变成了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数据,不能够根据限定条件:例如“只能是数字,必传”等做出合理的回应。

 
 
 

个人公众号谢谢各位老铁支持

写api接口神器--带你5分钟了解swagger的更多相关文章

  1. web api写api接口时返回

    web api写api接口时默认返回的是把你的对象序列化后以XML形式返回,那么怎样才能让其返回为json呢,下面就介绍两种方法: 方法一:(改配置法) 找到Global.asax文件,在Applic ...

  2. Swagger解决你手写API接口文档的痛

    首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛     苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...

  3. 一步一步学swift之:自己写Api接口-PHP

    想要自己一个人完成app,那么后台接口也必须自己动动手.不用担心,其实很简单的,给自己信心!下面就以登录注册为例,做一个api接口 首先在mac上搭建PHP环境,下载 MAMP Pro for Mac ...

  4. 使用js+Ajax请求API接口数据-带请求头方式

    C# http请求带请求头部分 先上代码: <script type="text/javascript"> function zLoginCheck() { var A ...

  5. 一分钟内搭建全web的API接口神器json-server详解

    JSON-Server 是一个 Node 模块,运行 Express 服务器,你可以指定一个 json 文件作为 api 的数据源. 安装json-server npm install -g json ...

  6. Yii2 使用 RESTful 写API接口 实例

    Yii2 使用 RESTful? 其实 Yii2 框架本身就对 RESTful 是友好支持的,具体可以看官方文档(http://www.yiichina.com/doc/guide/2.0/rest- ...

  7. nodejs+express+mongodb写api接口的简单尝试

    1:启动mongodb服务 我的mongoDB的安装目录:E:\mongoDB\bin,版本:3.4.9 打开cmd  -> e:(进入e盘) -> cd mongoDB/bin(进入mo ...

  8. PHP开发api接口安全验证

    php的api接口 在实际工作中,使用PHP写api接口是经常做的,PHP写好接口后,前台就可以通过链接获取接口提供的数据,而返回的数据一般分为两种情况,xml和json,在这个过程中,服务器并不知道 ...

  9. php的api接口

    在实际工作中,使用PHP写api接口是经常做的,PHP写好接口后,前台就可以通过链接获取接口提供的数据,而返回的数据一般分为两种情况,xml和json,在这个过程中,服务器并不知道,请求的来源是什么, ...

随机推荐

  1. Git - 对一组仓库进行配置

    对一组仓库使用一套配置,另一组仓库使用另一套配置的需求也是有的,比如公司仓库的配置和我个人项目的仓库配置并不完全相同,每次都修改单个仓库的配置太麻烦并且可能会粗心忘改了以错误的配置进行提交,如何对一个 ...

  2. seleniumIDE回放找不到页面元素

    seleniumIDE回放找不到页面元素 如下所示,自动回放就报错,手动执行就不报错.

  3. gunicorn+nginx配置方法

    对于gunicorn+nginx的配置,理解他们之间的关系很重要,以及最后如何确认配置结果是正确的也很重要 nginx 配置文件: 修改这个配置文件有3个用处: 假设服务器本身的Ip是A称为ip-A, ...

  4. 阶段3 1.Mybatis_12.Mybatis注解开发_7 Mybatis注解开发一对多的查询配置

    一对多的配置,一个用户对应多个账户 需要在Accout里面增加根据用户的uid查询的方法 在user里面指定子一对多的查询配置 换行显示 测试 把这里注销掉.测试延迟加载,代码注释掉后,延迟加载就没有 ...

  5. lazarus 给应用程序创建 配置文件哈哈

    lazarus 给应用程序创建 配置文件哈哈procedure TForm1.Button2Click(Sender: TObject);beginForceDirectoriesUTF8(GetAp ...

  6. http层负载均衡之 haproxy实践篇

    方案 上篇文章讲到了负载均衡的相关理论知识,这篇文章我打算讲讲实践方法以及实践中遇到的问题 方案:haproxy http层负载均衡 安装一个haproxy服务,两个web服务 haproxy:192 ...

  7. jmeter链接数据库操作

    jmeter链接数据库操作步骤 首先要先下载mysql-connector-java-5.1.39-bin.jar驱动包 链接:https://pan.baidu.com/s/14F4rp4uH1hX ...

  8. kafka学习(七)

    跨集群数据镜像 跨集群镜像的使用场景 1.区域集群和中心集群 2.冗余,发生紧急情况下使用第二个集群,保存相同的数据. 3.云迁移   多集群架构   跨集群中心通信的一些现实情况 1.高延迟 2.有 ...

  9. SpringBoot 使用JPA+MySQL+Thymeleaf 总结 二

    SpringBoot 使用JPA+MySQL+Thymeleaf 总结 一 SpringBoot 使用JPA+MySQL+Thymeleaf 总结 二 方法一 使用原生sql查询 或者 为方法名增加 ...

  10. mysqlreport 安装&使用

    安装包:mysqlreport-3.5.tgz 下载地址:http://hackmysql.com/scripts/mysqlreport-3.5.tgz 安装办法:[root@nagios ~]# ...