5分钟了解swagger

原创 2017年08月27日 20:47:06

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

版权声明:本文为RyuGou原创文章,未经博主允许不得转载。

Swagger简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。...
  • wangnan9279
  • wangnan9279
  • 2015年03月22日 21:09
  • 172478

Swagger原理解析

swagger简介        swagger确实是个好东西,可以跟据业务代码自动生成相关的api接口文档,尤其用于restful风格中的项目,开发人员几乎可以不用专门去维护rest api,这个...
  • qq_25615395
  • qq_25615395
  • 2017年04月18日 15:45
  • 5824

swagger快速开发

swagger 学习笔记搭建环境: 1,jdk1.8 2,idea 3,spring-boot-starter-parent版本1.5.6.RELEASE 4,springfox-swagger2 ...
  • xxoo00xx00
  • xxoo00xx00
  • 2017年08月14日 20:14
  • 826

swagger使用笔记

在很多框架中,都会看到这个词汇, 这个组件,到底是干什么的呢?我所了解的swagger常见功能: 1. API文档生成工具,用户对系统中的API进行说明,以及提供测试接口. 2. 代码自动生成功能...
  • hzwy23
  • hzwy23
  • 2017年04月14日 22:53
  • 3240

Swagger与SpringMVC项目整合

Swagger与SpringMVC项目整合 为了方便的管理项目中API接口,在网上找了好多关于API接口管理的资料,感觉目前最流行的莫过于Swagger了,功能强大,UI界面漂亮,并且支持在线测...
  • linlzk
  • linlzk
  • 2016年03月14日 13:54
  • 1938

swagger

@GetMapping,@PostMapping,@PutMapping,@DeleteMapping,@PutMapping 这个注解的作用是当前台界面调用Controller处理数据时候告诉控制...
  • Winnie_chenqian
  • Winnie_chenqian
  • 2018年01月22日 17:03
  • 25

swagger配置-转载

在知乎上看了这篇文章,简单明了上手swagger,我自己懒得写了。这个以后可以对着他写。码代码。 Spring Boot中使用Swagger2构建强大的RESTful API文档 ...
  • wanghaitao4j
  • wanghaitao4j
  • 2018年01月16日 21:14
  • 109

使用swagger 遇到 Can't read swagger JSON 错误

最近在做项目的过程中,使用到了swagger ,按照swagger 正常设置之后,在浏览器中查看接口的时候却遇到了 Can't read swagger JSON 错误,刚开始没有头绪,由于不是很熟悉...
  • shecanwin
  • shecanwin
  • 2017年02月18日 14:59
  • 5331

Swagger使用

Swagger 使用文档 G-SISI 2016-04-05  一、概述      swagger简述 Swagger API框架,用于管理项目中API接口,属当前最流行的API接口管理工...
  • blucelee2
  • blucelee2
  • 2016年04月13日 10:04
  • 10666

Swagger框架学习分享

Swagger框架学习分享 转至元数据结尾 Created and last modified by 刘新宇 大约1分钟以前 转至元数据起始 */一、背景介绍1.1....
  • u010827436
  • u010827436
  • 2015年03月18日 17:54
  • 19984
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:5分钟了解swagger
举报原因:
原因补充:

(最多只允许输入30个字)