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\)

二、nodehttp-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 微服务。代码结构如下:

三、修改&运行服务端:

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根目录,稍作修改即可。

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 的具体用法请查看网络相关资料,此处不再赘述。

原文地址:https://www.cnblogs.com/FlyAway2013/p/7510279.html

原文地址:https://www.cnblogs.com/anqli-java/p/8819510.html

时间: 2024-11-12 00:44:56

swagger 基础入门的相关文章

Android基础入门教程——10.12 传感器专题(3)——加速度-陀螺仪传感器

Android基础入门教程--10.12 传感器专题(3)--加速度/陀螺仪传感器 标签(空格分隔): Android基础入门教程 本节引言: 本节继续来扣Android中的传感器,本节带来的是加速度传感器(Accelerometer sensor)以及 陀螺仪传感器(Gyroscope sensor),和上一节的方向传感器一样有着x,y,z 三个轴, 还是要说一点:x,y轴的坐标要和绘图那里的x,y轴区分开来!传感器的是以左下角 为原点的!x向右,y向上!好的,带着我们的套路来学本节的传感器吧

Android基础入门教程——8.1.3 Android中的13种Drawable小结 Part 3

Android基础入门教程--8.1.3 Android中的13种Drawable小结 Part 3 标签(空格分隔): Android基础入门教程 本节引言: 本节我们来把剩下的四种Drawable也学完,他们分别是: LayerDrawable,TransitionDrawable,LevelListDrawable和StateListDrawable, 依旧贴下13种Drawable的导图: 1.LayerDrawable 层图形对象,包含一个Drawable数组,然后按照数组对应的顺序来

Android基础入门教程——8.1.2 Android中的13种Drawable小结 Part 2

Android基础入门教程--8.1.2 Android中的13种Drawable小结 Part 2 标签(空格分隔): Android基础入门教程 本节引言: 本节我们继续来学习Android中的Drawable资源,上一节我们学习了: ColorDrawable:NinePatchDrawable: ShapeDrawable:GradientDrawable!这四个Drawable~ 而本节我们继续来学习接下来的五个Drawable,他们分别是: BitmapDrawable:Insert

Android基础入门教程——2.3.12 Date &amp; Time组件(下)

Android基础入门教程--2.3.12 Date & Time组件(下) 标签(空格分隔): Android基础入门教程 本节引言: 本节我们来继续学习Android系统给我们提供的几个原生的Date & Time组件,他们分别是: DatePicker(日期选择器),TimePicker(时间选择器),CalendarView(日期视图),好吧, 其实一开始让我扣这几个玩意我是拒绝的,因为在我的印象里,他们是这样的: 简直把我丑哭了,有木有,终于知道为什么那么多人喜欢自定义这种类型的

Android基础入门教程——2.1 View与ViewGroup的概念

Android基础入门教程--2.1 View与ViewGroup的概念 标签(空格分隔): Android基础入门教程 本节引言: 告别了第一章,迎来第二章--Android中的UI(User Interface)组件的详解, 而本节我们要学习的是所有控件的父类View和ViewGroup类!突发奇想,直接翻译官方文档对 这两个东西的介绍吧,对了,天朝原因,google上不去,Android developer上不去,我们可以 改hosts或者用vpn代理,当然也可以像笔者一样使用国内的API

DAX基础入门 – 30分钟从SQL到DAX — PowerBI 利器

看到漂漂亮亮的PowerBI报表,手痒痒怎么办?! 有没有面对着稀奇古怪的DAX而感到有点丈八金刚摸不着头脑或者干瞪眼?! 有没有想得到某个值想不出来DAX怎么写而直跳脚!? 看完这篇文章,你会恍然大悟,捂脸偷笑.呼呼呼~ 前言: 这篇文章对于具有一点SQL查询基础人会十分容易理解,譬如:掌握SELECT,SUM,GROUP BY等. 注:此文不涉及到Filter Context(筛选上下文)的介绍. 正文: 对于对SQL有一定了解的人来说,咋看DAX,怎么都不习惯. 但是,如果理解以下几个后,

Linux 基础入门----推荐课程

Linux 基础入门课程:https://www.shiyanlou.com/courses/1 很好的一门Linux基础课,精炼.简洁!推荐! 课程内容: 第1节 Linux 系统简介 https://www.shiyanlou.com/courses/1/labs/1/document 第2节 基本概念及操作 https://www.shiyanlou.com/courses/1/labs/2/document 第3节 用户及文件权限管理 https://www.shiyanlou.com/

从零基础入门JavaScript(1)

从零基础入门JavaScript(1) 1.1  Javascript的简史 1995年的时候   由网景公司开发的,当时的名字叫livescript    为了推广自己的livescript,搭了java顺风车,改名为javascript 与此同时,     微软因此在自身的浏览器里,也推出了自己的脚本语言 jscript 1997年时候,  由ECMA(欧洲计算机制造商协会)出面,推出了一套javascript的规范,Ecmascript ,规范提出js由三部分组成 JS的组成: ECMAS

saltstack之基础入门系列文章简介

使用saltstack已有一段时间,最近由于各种原因,特来整理了saltstack基础入门系列文章,已备后续不断查阅(俗话说好记性不如烂笔头),也算是使用此工具的一个总结.saltstack的前六篇文章主要讲述了saltstack的安装.远程执行.配置管理.数据系统以及jinjia模板等知识点,从第七篇往后的文章是一些使用saltstack的案例,包括系统初始化,rpm包以及源码安装等. 博客中saltstack系列的文章,适合初学者从零开始学习直到逐渐熟练使用.文章具有一定的连贯性,如果没有任