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数据,不能够根据限定条件:例如“只能是数字,必传”等做出合理的回应。

了解swagger的更多相关文章

  1. ABP框架 - Swagger UI 集成

    文档目录 本节内容: 简介 Asp.net Core 安装 安装Nuget包 配置 测试 Asp.net 5.x 安装 安装Nuget包 配置 测试 简介 来自它的网页:“...使用一个Swagger ...

  2. ABP项目中使用Swagger生成动态WebAPI

    本文是根据角落的白板报的<使用ABP实现SwaggerUI,生成动态webapi>一文的学习总结,感谢原文作者角落的白板报. 1 安装Swashbuckle.core 1.1 选择WebA ...

  3. 用Swagger生成接口文档

    Swagger简介 在系统设计的时候,各个应用之间往往是通过接口进行交互的.因此接口的定义在整个团队中就变得尤为重要.我们可以把接口的规范用接口描述语言进行描述,然后Swagger可以根据我们定义的接 ...

  4. 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)

    对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...

  5. 使用swagger作为restful api的doc文档生成

    初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...

  6. ASP.NET Core 中文文档 第二章 指南 (09) 使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档

    原文:ASP.NET Web API Help Pages using Swagger 作者:Shayne Boyer 翻译:谢炀(kiler) 翻译:许登洋(Seay) 对于开发人员来说,构建一个消 ...

  7. 在ASP.NET Core Web API上使用Swagger提供API文档

    我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...

  8. ASP.NET WebApi 文档Swagger深度优化

    本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明博客园蜗牛原文地址,cnblogs.com/tdws   写在前面 请原谅我这个标题党,写到了第100篇随笔,说是深度优化,其实也并没有什么深度 ...

  9. ASP.NET WebApi 文档Swagger中度优化

    本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明原文地址:www.cnblogs.com/tdws   写在前面 在后台接口开发中,接口文档是必不可少的.在复杂的业务当中和多人对接的情况下,简 ...

  10. NSwagStudio for Swagger Api

    本案例主要说明如何使用NSwag 工具使用桌面工具快速生成c# 客户端代码.快速的访问Web Api. NSwagStudio 下载地址 比较强大.可以生成TypeScript.WebApi Cont ...

随机推荐

  1. 微信小程序入门文档

    一 基本介绍 微信专门为小程序开发了一个ide叫做微信开发者工具 最新一版的微信开发者工具,把微信公众号的调试开发工作也集成了进去,可以更换开发模式. https://mp.weixin.qq.com ...

  2. HDU-1269-迷宫城堡(强连通 模板)

    链接:https://vjudge.net/problem/HDU-1269 题意: 为了训练小希的方向感,Gardon建立了一座大城堡,里面有N个房间(N<=10000)和M条通道(M< ...

  3. GPU程序缓存(GPU Program Caching)

    GPU程序缓存 翻译文章: GPU Program Caching 总览 / 为什么 因为有一个沙盒, 每一次加载页面, 我们都会转化, 编译和链接它的GPU着色器. 当然不是每一个页面都需要着色器, ...

  4. jquery扩展方法详解

    http://www.jb51.net/article/51079.htm https://www.cnblogs.com/xuxiuyu/p/5989743.html     ---更详细

  5. Tkinter 的三大布局管理器 pack、grid 和 place用法汇总

    学习python的tkinter免不了要对各个组件进行位置的排放与设定,常用的布局管理器有grid,pack和place.这三种均用于同一父组件下的组件布局,但是也是有区别的,先看下他们各自的含义吧. ...

  6. ef 操作 mysql 中文乱码问题

    1.保证mysql数据的编码为utf8 启动mysql mysql -hlocalhost -uroot -p 输入密码 show VARIABLES like 'character_%'; SET  ...

  7. P4869 罪犯分组

    思路: 明显的dp,虽然我想到了二进制模拟,想到了转移,但还是先看了题解,原来真是这样,,,,不是第三题吗? 用f[i]表示,对于前i个罪犯最少需要分几组. 对于每个状态用二进制表示,第i位上1,0表 ...

  8. nodejs 中的异步之殇

    nodejs 中的异步之殇 终于再次回到 nodejs 异步中,以前我以为异步在我写的文章中,已经写完了,现在才发现,还是有很多的地方没有想清楚,下面来一一说明. 模块同步与连接异步 大家应该,经常使 ...

  9. asp.net重启web应用程序域

    我把加载到static静态变量中了,是在数据库中存的,这样每次改了一下必须要重启一下web应用程序,每次去iis操作太麻烦了,于是找的了这个重启的办法,一句话代码: System.Web.HttpRu ...

  10. SQL函数TIMEDIFF在Java程序中使用报错的问题分析

    需求背景 (读者可略过)司机每天从早到晚都会去到不同的自动售货机上补货,而且补货次数和路线等也是因人而异,补货依据是由系统优化并指派.但是目前系统还无法实施有效指挥和优良的补货策略,司机的补货活动因此 ...