对于IT码农来说API文档是再熟悉不过的东东。特别是API文档的编辑和交流更是相当的虐心。
就个人来说,使用过编辑API文档的工具,从最原始的口口相授,到接下的苦逼word和上个项目在用的dokuwiki,没有一个让自己很满意的。要么是编辑太麻烦,升级时还要传来传去,如word,要么及时可以在线编辑吧,又得去熟悉相关的编辑语法,如wiki。更要命的是有时一个接口明明自测是可以的,然后有一天前端人员跑过来跟你说,接口调用失败,这个时候别提有多郁闷了。因为你要根据接口文档在rest工具上重新跑一遍,测下接口是否真的用不了,参数少点还好说,有时好几个参数就更繁琐了。每当这个时候,就总在想,如果有一个工具既可以当api接口文档来看,也可以直接测试,马上看到结果,那无论对于前端还是后端都是爽歪歪的。
偶尔一个机会在一个技术交流群里看到有人提到有个api工具挺好用的,swagger ui。当即上网搜索了下,用的人还蛮多的,于是到其官网小逛一下。这一逛可把我乐开了花,这不是我正一直苦苦找寻的吗?界面简单明了,功能强大,可直接在线表单式测试接口(具体效果可以看文章末尾)。于是,我就兴冲冲的下载,看说明文档,写demo。前前后后总共折腾了2天,后来发现使用上还是有些许的不方便。主要有2点,其一,集成使用上,要么通过服务端代码嵌入,这样就跟业务代码偶尔在一起了,而且无法单独部署;要么手动编写对应的json格式文档,文档结构又比较复杂,而且无法多个人协助。其二,如果是手动编辑json文档的话又不支持自定义格式,只能一次一层还不能嵌套,蛋疼不已。
我个人是觉得,文档就是文档,最好不要跟业务代码耦合在一起,于是一开始就摈弃了服务端集成方式,就想着看下有没什么简便的方法来编写json格式文档。本来有打算写个小工具以表单的形式来编辑,这样就爽多了。可惜只是想想而已,后来其他事忙着,也就没去再想这个事。
很凑巧,又在一个群里看到有位哥们在推广他的网站SosoApi(www.sosoapi.com),说是专注于API接口管理和线上线下测试的,而且刚好又是用的SwaggerUI。于是,很好奇的点击进去一探究竟,看下是怎样一个网站,名字还这么奇怪,soso。。。不用不知道,一用吓一跳,这不就是专门为我写的吗?编辑起Swagger UI的json文档那是相当轻松啊,而且不但可以在线预览还可以下载到本地部署。估计网站的攻城狮也觉得API文档还是本地比较保险比较安全吧。这个必须赞一个。
虽然好久不写技术blog了,不过,这个网站确实不错,有在用SwaggerUI的同行或打算从原来API接口文档的苦逼中跳出来的确实可以试着用下。
相关推荐
swagger-editor、swagger-ui和swaggerui( tomca)版,windows x64 nodejs安装版项目包下载
Visual Studio 2017下Asp.Net WebApi应用添加SwaggerUI 附详细解说
前端项目-swagger-ui,Swagger UI是一个HTML、JavaScript和CSS资产的无依赖性集合,可以从符合Swagger的API动态生成漂亮的文档。
Swagger工具包。在Tomcat上直接运行版。 添加了sosoapi的SwaggerUI的扩展插件。
swagger UI
现在市面上的swagger UI不足之处 1、原生UI显示的有些不够漂亮和清晰,特别是request 的model部分 2、每个服务都需要引入一套资源文件,不能作为一个中间件为其他API使用 3、默认通用配置繁琐,每个项目都需要复制...
https://blog.csdn.net/weixin_42739423/article/details/87773763 spring整合swagger的ui文件
flask-swagger-ui 简单的Flask蓝图,用于将添加到flask应用程序。 包含的Swagger UI版本:3.36.0。 安装 pip install flask-swagger-ui 用法 示例应用程序: from flask import Flask from flask_swagger_ui ...
golang-swaggerui-example Golang-swaggerui-example是一个示例存储库,用于在您的Golang项目中使用SwaggerUI设置API文档。 详细说明可在。 API互动 可以通过访问localhost:8080 / swaggerui /访问SwaggerUI,有关...
Swagger UI
Java-springBoot+swaggerUI2整合
为你的Flask API提供毫不费力的Swagger UI
配置简单,可以运行的maven 工程
整合Springboot2.0,swagger接口文档。Swagger 自定义UI界面,美观,蓝色风格,实测通过。欢迎大家下载
Swagger UI是一款RESTFUL接口的文档在线自动生成 功能测试功能软件。 现在多数的项目开发中,网站和移动端都需要进行数据交互和对接,这少不了使用REST编写API接口这种场景。例如有些团队,移动端交由了另一团队...
此仓库表示swagger-ui-react的自定义版本,并为基础的swagger-ui构造函数添加了一些传递swagger-ui 。 我们需要使用swagger-ui-react (vs. swagger-ui ),因为它将React列为peerDependency ,这使得它可以很好地与...
一个简便的django app将swagger ui搬到项目中展示
:sparkles: Swagger UI插件 由维护的有用的Swagger UI插件的多包存储库。 :backhand_index_pointing_right: 可用插件 :当OAS 3.0 servers为空或丢失时,进入仅文档模式 贡献 随时打开问题并提出修复错误,添加...
Swagger-ui-plugin合同 这是一个插件,这使得该的操作(的x-contracts )。 用法 将插件包含在Swagger UI中的方法有两种:通过npm和通过unpkg 。 通过npm 使用npm安装模块: npm install --save swagger-ui-...