5分钟了解swagger

5分钟了解swagger

https://blog.csdn.net/i6448038/article/details/77622977

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

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

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏Linyb极客之路

互联网常见架构接口压测性能分析及调优手段建议

常见的互联网架构中,一般都能看到spring+mybatis+mysql+redis搭配的身影,在我所服务的公司亦是如此。一般来说,应用内部的接口都是直接调用的...

2205
来自专栏Linyb极客之路

理解分布式系统中的缓存架构(下)

承接上一篇《理解分布式系统中的缓存架构(上)》,介绍了大型分布式系统中缓存的相关理论,常见的缓存组件以及应用场景,本文主要介绍缓存架构设计常见问题以及解决方案,...

1111
来自专栏圣杰的专栏

DDD理论学习系列(9)-- 领域事件

1. 引言 A domain event is a full-fledged part of the domain model, a representati...

2619
来自专栏码匠的流水账

OpenMessaging概览

OpenMessaging是阿里牵头发起的分布式消息模型标准,其api规范首先在rocketmq中落地实现。通过这个标准可以简化各种消息中间件的高复杂性和不兼容...

2581
来自专栏程序员互动联盟

【专业技术】Node.js 究竟是什么?

简介 如果您听说过 Node,或者阅读过一些文章,宣称 Node 是多么多么的棒,那么您可能会想:“Node 究竟是什么东西?” 即便是在参阅 Node 的主页...

3357
来自专栏java思维导图

分布式之消息队列复习精讲

庆幸的是两位朋友都很有上进心,于是博主写这篇文章,帮助他们复习一下关于消息队列中间件这块的要点

1243
来自专栏C++

python笔记:#006#程序执行原理

1201
来自专栏编程

开发一款app从PHP到API接口

一、先简单回答两个问题: 1、PHP 可以开发客户端? 答:不可以,因为PHP是脚本语言,是负责完成 B/S架构 或 C/S架构 的S部分,即:服务端的开发。(...

4109
来自专栏北京马哥教育

大型网站的灵魂——性能

Via: http://blog.jobbole.com/84433/ 前言 在前一篇随笔《大型网站系统架构的演化》中,介绍了大型网站的演化过程,期间穿插了一...

3426

使用Node.js构建API网关

当微服务架构中的服务被外部的客户端访问时,可以共享有关身份验证和传输的一些常见请求。API网关提供了一个共享层去处理服务协议之间的差异,同时满足特定客户端(像P...

4249

扫码关注云+社区

领取腾讯云代金券