swagger 基础入门
目录
Swagger简介 4
安装 4
一、 Node.js 安装 4
二、 node中http-server安装 4
三、 下载swagger-editor 4
四、 启动 swagger-editor 5
五、 使用浏览器访问http://localhost 5
使用 5
一、 编写API 文档: 7
二、 生成服务端代码: 8
三、 修改&运行服务端: 9
四、 创建&运行客户端: 11
1. 使用swagger-editor 的web 界面: 11
2. 使用swagger-editor生成的客户端代码 14
3. 使用chrome 的 postman 插件 15
Swagger简介
Swagger包括Swagger Editor, Swagger UI等很多部分,这里我们主要讲一下Swagger Editor。它是一个完全开源的项目,并且它也是一个基于Angular的成功案例。
在Swagger Editor中,我们可以基于YAML等语法定义我们的RESTful API,然后它会自动生成一篇排版优美的API文档,并且提供实时预览。简单说就是可以边编写API 边预览边测试。
在Swagger UI中,我们不能进行编写API ,但是我们可以预览或者测试。
安装
一、Node.js 安装
swagger 是用node写的,所以需要先按照node。安装nodejs后node和npm会一并安装。
windows 中 直接运行node-v8.1.2-x64.msi 即可完成安装(我已经下载好,位于: \\10.9.60.201\shares\)
二、node中http-server安装
任一cmd窗口,执行npm install -g http-server
三、下载swagger-editor
安装swagger-editor 有多种方式,
l 从github 下载安装。 这个方式可能行不通,因为下载通常很慢。
l 从官网下载swagger-editor.zip,解压即可。(已共享)
四、启动 swagger-editor
在swagger-editor的根目录打开cmd窗口,执行http-server ,默认为8080端口 ,若想更换端口则使用如下命令 http-server –p 80 或者修改:C:\Users\Administrator\AppData\Roaming\npm\node_modules\http-server\bin\http-server 中 84行 portfinder.basePort = 8080; 改为自己想要的端口。
五、使用浏览器访问http://localhost
结果:
说明:
界面左边是api 文件的 yaml 描述文件, 左边部分可以直接编辑API文档,编辑会立即更新到右边视图。右边是swagger-UI,可以查看文档,并直接进行API的测试。
使用
l 示例。
swagger 内置了很多个examples。通过File→Open Example… 打开各示例文档:
l 设置。
通过 Preference可以进行各种偏好设置:
一、编写API 文档:
我们可以参照swagger-editor 的示例,直接修改,然后生成自己的文档。
几个关键地方需要修改:
- host 改为本地ip:port
- basePath 改为项目名或模块名
swagger-editor 有自动纠错的功能,编写的API 文档应该保证没有错误。这样才能发布。
编写完毕后, 我们可以把它保存下来。 可选格式为yaml/json :
当然,我们也可以把写好的yaml/json 文档导入然后修改、测试。
二、生成服务端代码:
Swagger-editor的强大功能,在于其可以生成很多种语言的服务端/客户端代码, 同时服务端代码中包含了Swagger-UI。 如下, 个人认为服务端中 其中 Node.js、Python Flask、Spring 语言的代码比较有价值,值得研究。
Spring 服务端代码适合后端开发人员,但是其生成的代码比较简单,而且不能直接使用, 需要做一些修改。
生成代码前, 我们确保已修改我们文档的关键地方:
host: localhost:8080
basePath: /projectABC
以 Swagger Petstore (Simple) 为例, 生成的spring 服务端代码本质上是一个spring-boot 微服务。代码结构如下:
三、修改&运行服务端:
l Spring 服务端: spring-server-generated.zip
src\main\java\io\swagger\api包下面的所有Api/ApiController结尾的类需要修改, 如PetIdApi 、 PetIdApiController 中所有的Void 改成 Pet。
ApiController结尾的类的public方法需要完成一些mock操作, 也就是—— // do some magic!
public ResponseEntity<Pet> petIdGet(@ApiParam(value = "ID of the pet",required=true ) @PathVariable("petId") String petId, HttpServletRequest request) {
// do some magic!
System.out.println("petId = " + petId);
Pet pet = new Pet();
pet.setName("lk 111");
pet.setBirthday(1234);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.TEXT_PLAIN);
ResponseEntity<Void> responseEntity = new ResponseEntity<>(headers, HttpStatus.OK);
ResponseEntity<Pet> ok = responseEntity.ok(pet);
return ok;
}
修改完成后双击运行 项目的maven 构建: spring-boot 即可:
由于某些原因, swagger生成的Spring 服务端代码没有UI 界面, 也就是 没有 swagger-UI。 当然, 只要我们简单修改,就完成UI 功能:
将swagger-editor-UI.zip(已共享) 放到web根目录,稍作修改即可。
l Swagger-editor 生成的nodejs 服务端代码(推荐), 不用修改就可以直接运行:
解压nodejs-server-server-generated.zip , 然后cmd 进入nodejs-server-server 目录,npm start 即可运行,访问http://localhost:8080/docs 可以看到swagger-UI :
然后, 我们就可以进行测试等操作。
四、创建&运行客户端:
服务端启动之后, 就可以进行访问测试。访问测试有多种方式,
1 是直接使用swagger-editor 的web 界面
2 是使用swagger-editor生成的客户端代码
3 是使用浏览器插件, 比如chrome 的 postman 插件
下面分别进行介绍:
1.使用swagger-editor 的web 界面:
举个栗子,我们现在准备测试GET /pets/{id} :
右边视图 -> /pets/{id} -> Try this operation , 填好参数,然后点击“Send Request”
不过,发送请求进行测试之前,我们需要做两件事:
1 由于我们是在浏览器中进行测试不同网站的接口。 我们实际上已经跨域,出于安全原因,浏览器默认不允许跨域。故我们需要做一些处理,比如安装一些插件。Chrome 上安装一个Allow-Control-Allow-Origin 拓展:
(chrome 拓展文件为www.cnplugins.com_fhbjgbiflinjbdggehcddcbncdddomop_4_7_2_.crx, 已共享, 如果无法安装, 那么需要从chrome 商店进行下载-安装, https://chrome.google.com/webstore/category/extensions?hl=zh-CN)
2 由于当前版本的swagger-editor 本身存在一些问题(发送的请求无法设置Content-Type请求头), 我们需要修改我们的后端代码:
src\main\java\io\swagger\api包下面的所有Api结尾的类需要修改,将其中每个方法的RequestMapping 部分的 consumes 去掉:
后端代码修改完需要重启。
处理完毕,我们就可以进行API 接口测试了:
2.使用swagger-editor生成的客户端代码
swagger-editor可以生成 很多语言版本的客户端代码, 个人认为其中 JavaScript、java 比较有研究价值的,
由于某些原因,部分语言可能无法生成代码:
如同swagger-editor生成的服务端代码, 其生成的客户端代码也可能有问题。需要做一些修改:
以生成的java代码为例, 需要将 src\main\java\io\swagger\api包下面的所有Api结尾的类需要修改, 其中的Void 改成 Pet。
src\test\java\io\swagger\client\api 包的类需要修改, 其中的Void 改成 Pet。
运行测试方法, 完成测试:
3.使用chrome 的 postman 插件
下载安装postman,
运行:
设置请求头:
Postman 的具体用法请查看网络相关资料,此处不再赘述。
swagger 基础入门相关推荐
- elementUi基础入门学习
elementUi基础入门学习 1.前后端分离(理解) 1.1什么是前后端分离 1.2 前后端分离开发的理解 1.3 为什么要进行前端分离开发: 2 . 先去搭建前端服务 3 elementui 4 ...
- 用python循环语句求素数_Python基础入门_3条件语句和迭代循环
Python 基础入门前两篇: Python 基础入门--简介和环境配置 Python基础入门_2基础语法和变量类型 这是第三篇内容,主要简单介绍条件语句和迭代循环语句,内容也比较简单,目录如下: 条 ...
- MAYA 2022基础入门学习教程
流派:电子学习| MP4 |视频:h264,1280×720 |音频:AAC,48.0 KHz 语言:英语+中英文字幕(根据原英文字幕机译更准确)|大小解压后:3.41 GB |时长:4.5小时 包含 ...
- Blender 3.0基础入门学习教程 Introduction to Blender 3.0
成为Blender通才,通过这个基于项目的循序渐进课程学习所有主题的基础知识. 你会学到什么 教程获取:Blender 3.0基础入门学习教程 Introduction to Blender 3.0- ...
- 三维地形制作软件 World Machine 基础入门学习教程
<World Machine课程>涵盖了你需要的一切,让你有一个坚实的基础来构建自己的高质量的电影或视频游戏地形. 你会学到什么 为渲染或游戏开发创建高分辨率.高细节的地形. 基于Worl ...
- SketchUp Pro 2021基础入门学习视频教程
SketchUp Pro 2021基础入门学习视频教程 1280X720 MP4 |视频:h264,1280×720 |音频:AAC,44.1 KHz,2 Ch 流派:电子学习|语言:英语+中文字幕( ...
- Maya基础入门学习教程
Maya基础入门学习教程 视频:.MKV, 1280x720, 共57节课 时长 4小时25分钟,3GB 语言:英语+中文字幕(根据原英文字幕机译更准确)+原英文字幕 指导老师:Shane Whitt ...
- Maya2022基础入门学习教程
Maya2022基础入门学习教程 Maya 2022 Essential Training Maya2022基础入门学习教程 Maya 2022 Essential Training MP4 |视频: ...
- Blender基础入门学习教程 Learning Blender from Scratch
Blender基础入门学习教程 Learning Blender from Scratch 流派:电子学习| MP4 |视频:h264,1280×720 |音频:aac,48000 Hz 语言:英语+ ...
- json vue 对象转数组_vue 基础入门(一)修改
vue基础入门(一) 1. 什么是vue Vue.js(读音 /vjuː/, 类似于 view) 是一套构建用户界面的渐进式框架. Vue 只关注视图层, 采用自底向上增量开发的设计. Vue 的目标 ...
最新文章
- pip install transformers出现拒绝访问
- 第六次作业(C语言)
- H.264解码器ffmpeg完整优化代码(包括PC和Windows Mobile版本)
- Java三维文字特效设计_jQuery实现3D文字特效的方法
- jeecg-framework-3.1.0.RELEASE 正式发布
- An impassioned circulation of affection(尺取+预处理)
- ASP.NET--窗体实现淡入淡出效果
- 20162302 第七周作业
- mysql getname_mysql别名取不出值(getColumnLabel和getColumnName的区别)
- Unity中 创建射线的两种方法
- Ubuntu 16.04 利用Sakurafrp工具管理多节点多隧道ID 实现 ssh 内网穿透
- JQ树形菜单加表格混合使用:treeTable组件使用
- kvaser在linux下的二次开发
- python 邮件分类_python_NLP实战之中文垃圾邮件分类
- 巴黎世家土味病毒营销,B端创业初期,如何用营销壮大你的种子用户?
- 2022年中国大学排行榜出炉~
- element ui响应式布局笔记,适配笔记
- 想买个吉他英雄3的正版
- 帆软注册文件_报表组件FineReport加密狗注册机理及使用方法
- linux 中find命令下的-type f 代表什么意思
热门文章
- Linux网络管理常用命令:net-tools VS iproute2
- hdu.1429.胜利大逃亡(续)(bfs + 0101011110)
- Transact-SQL 语法约定
- 【LeetCode 剑指offer刷题】字符串题3:Reverse String
- 获取浏览器选中文本并操作
- VMware上安装CentOS系统(本人新手,欢迎大家多多指导和关照)
- [2017浙工大之江学院决赛 H] qwb与学姐(并查集,按秩合并,最小生成树,LCA)...
- Java期末设计(十三周)
- 笔记-as/400的CL命令
- 再谈指标体系建设的3点建议