Swagger

优质

小牛编辑

128浏览

2023-12-01

1 历史、现状和发展

Swagger：是一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，总体目标是使客户端和文档系统与服务器以同样的速度进行更新。Swagger倾向于在线测试接口和数据。并且这是一个完全开源的项目，并且它也是一个基于Angular的成功案例，我们可以下载源码并自己部署它，也可以修改它或集成到我们自己的软件中。

Swagger的创始人： Tony Tam

2009年Swagger框架启动，但是在当时Swagger API框架只是在Reverb内部开发的一个项目；

2011-10-11 1.0.1版本；2013-03-08 1.0.13；

2014年5月 Swagger的开放工作小组成立；

Swagger 2.0.24在2014年9月12日正式发布；

Swagger规范未来的发展将由SmartBear负责，这是一家位于马萨诸塞州的软件工具公司。

2016-07-20 2.1.5版本；2016-10-14 2.2.6版本；

2 安装和使用

2.1 安装

2.1.1 Swagger Editor安装

需要下载一个Swagger Editor，也可以直接使用在线版本http://editor.swagger.io/。

现在地址：git clone https://githup.com/swagger-api/swagger-editor.git

下载完成后进行本地配置（前提是已经安装好了Node.js），命令如下：

1.cd swagger-editor

2.npm install -g http-server

3.http-server （默认的是：8080端口）

4.http-server -p 7000 可以修改端口（临时）

效果图：默认端口：修改后的端口：

2.1.2 Swagger-UI的安装

现在地址：git clone https://githup.com/swagger-api/swagger-ui.git

Swagger UI的本地配置：

1,创建一个 node目录

mkdir node

2.初始化 node，创建package.json

~ > cd node

~ > node >npm init

3.安装express

~ > node >npm install express --save

效果图：

4 .创建index.js

~ > node > vim index.js

将一下代码复制到index.js中：

var express = require('express');

var app = express();

app.use('/static', express.static('public'));

app.get('/', function (req, res) {

    res.send('Hello World!');

});

app.listen(5000, function () {

    console.log('Example app listening on port 5000!');

});

5.创建public文件夹：

~ > node > mkdir public

把Swagger-UI文件中dist目录下的文件全部复制到public中：

效果图：

6.开启node

~ > node > node index.js

打开浏览器输入：localhost:3000/static/index.html

2.2 Swagger参数介绍

get/post/delete/ 是指这个接口对应的请求方式

tags 当前接口的分类

summary 是对这个接口进行的一个总体描述

description：对接口的描述

parameters: 接口需要传递的参数

- name: X-Auth-Token 参数的名字

in: header 他的值:header、path、formData Query body

description: /auth接口获取的token

required: true 两个值:true、false；true为必填项，false为非必填项

type: string 参数格式

2.3 使用

2.3.1开发环境介绍

maven 3.3

jdk 8+

spring 4.2.5

mybatis 3.4.1

swagger 1.0.2

2.3.2在pom.xml文件中添加swagger相关依赖

2.3.3自定义对swagger的配置

对于swagger的配置，其实对自定义一个与swagger相关的Config类，可以通过Java编码的实现配置。代码如下：

2.3.4对Swagger-UI进行配置

Swagger扫描解析得到的是一个json文档，所以对于用户使用不是很方便，但是通过swagger-ui，可以友好的展示解析得到的接口说明内容。从这里获取其所有的 dist 目录下东西放到需要集成的项目里，本文放入 src/main/webapp/目录下。

2.3.5运行项目，访问URL

URL是自己在index.html中定义的URL

2.4 示例

例子1：

@ApiParam(value = "token", required = true)

@RequestParam String token

Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。

例子2：

当参数太多的时候，需要定义太多的参数，排版看起来很不舒服。这个时候，可以使用对象来接收。 @ApiModel(value = "用户对象",description="user2")

public class User extends CommonParam{

}

Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。这里面存在一个小问题，当后端用对象User来接收参数的时候，Swagger自带的工具是这样的：

这种形式，并不是表单提交，或者把参数附加到URL的后面。我们只能手动构造URL，附带参数去提交。如果需要测试的话！

例子3：

Web前端/移动端HTTP请求方式：必须把参数，放到request请求的body中去。后端不能直接用request.getParam("token")这种。

获得request body中的数据，手动转换成目标数据。

String charReader(HttpServletRequest request) throws IOException {

    BufferedReader br = request.getReader();

    String str, wholeStr = "";
    while ((str = br.readLine()) != null) {
        wholeStr += str;
    }
    return wholeStr; 

}

1.参数不多的时候，推荐用例子1，用@ApiParam注解生成文档。swagger可视化界面，可以直接设置参数，发送请求来测试。

2.参数比较多的时候，推荐用例子2，用对象来接收参数，在对象里针对每个字段，@ApiModelProperty注解生成文档。swagger可视化界面，可以直接设置参数，但是无法接收到。

因此，推荐使用其它HTTP请求或POST模拟工具，发送请求，模拟测试。

3.不推荐例子3，不通用，局限性比较大。