SpringBoot18 Swagger、API接口文档生成、WireMock、模拟后台数据

迷思

2018-05-11

关注关注

1 Swagger

1.1 简述

前后端分离的项目需要前后端开发人员协同工作，后台开发人员需要给到前端开发者一套API文档；利用Swagger可以简单高效的帮助后台开发者生成RestfulAPI开发文档

官网地址：点击前往

1.2 使用步骤

1.2.1 引入swagger相关依赖

<!-- 自动生成restfulAPI文档相关 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

1.2.3 支持注解

在SpringBoot项目的启动类上标注@EnableSwagger2 使项目支持 swagger 注解

1.2.4 文档注解

在需要生成API文档的地方标注相应注解即可

》方法级别

@ApiOperation(value = "查询所有用户信息")

SpringBoot18 Swagger、API接口文档生成、WireMock、模拟后台数据

》参数级别（单个参数）

@ApiParam(value = "订单ID")

》参数级别（参数是一个实体类）

@ApiModelProperty(value = "用户ID")

技巧01：直接在实体类中的某个字段上添加@ApiModelProperty(value = "用户ID")

1.2.5 访问 swagger-ui.html

技巧01：如果项目设置了上下文路径，那么就需要在前面添加上下文路径，例如

http://127.0.0.1:9999/dev/swagger-ui.html

2 WireMock

前端开发人员需要一些后天的模拟数据，后台开发人员可以利用WireMock模拟一些数据供前端人员调用

技巧01：WireMock 是一个单独的服务器

2.1 单独使用WireMock

直接将数据放到指定文件，在进行一些配置后再启动WireMock服务器就可以啦

技巧01：这种方法使用简单但是对于后台开发人员不太方便，详细使用方法请参见百度

技巧02：这种方法适合前端人员使用（PS：前端人员拿到了后台给他的JSON文件）

2.2 在项目中集成WireMock

2.2.1 下载WireMock的jar包

到WireMock的官网把jar包下载到本地

WierMock官网：点击前往

2.2.2 启动WierMock

下载的WireMock就相当于一个项目的jar包，我们只需要在JVM上运行这个jar包即可

技巧01：进入到WireMock的jar包所在的文件夹，然后运行这个jar包

技巧02：在运行这个jar包时可以指定端口等信息，详情参见官方文档

java -jar wiremock-standalone-2.17.0.jar --port=8062

2.2.3 在SpringBoot项目中集成（简单）

2.2.3.1 下载先关jar包

<dependency>
            <groupId>com.github.tomakehurst</groupId>
            <artifactId>wiremock</artifactId>
            <version>2.14.0</version>
        </dependency>

2.2.3.2 发布信息

》连接配置

技巧01：需要配置WireMock的IP地址以及端口，如果是本地就不需要配置IP地址，直接配置端口即可

》清空上一次的发布信息

》执行main方法进行消息发布

package com.example.wiremock.util;

import org.apache.commons.io.FileUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;

import static com.github.tomakehurst.wiremock.client.WireMock.*;

/**
 * @author 王杨帅
 * @create 2018-05-11 9:29
 * @desc
 **/
public class WireMockServerUtil02 {
    public static void main(String[] args) throws IOException {

        // 01 连接配置
        configureFor(8062); // 配置连接信息（PS:这个端口必须和启动WireMock的端口保持一致）

        // 02 清空发布信息
        removeAllMappings(); // 清空上一次的发布信息

        // 03 发布新信息
        stubFor(
                get(urlPathEqualTo("/wiremock/test")) // 设置请求路径
                        .willReturn(
                                aResponse() // 设置响应信息
                                        .withBody("{\"id\":12,\"name\":null,\"password\":null}") // 响应数据
                                        .withStatus(200) // 响应状态码
                        )
        );

    }

}

WireMockServerUtil02.java

2.2.3.3 请求WireMock中的模拟数据

技巧01：IP地址、端口、请求路径都是WireMock的，不是SpringBoot项目的

2.2.4 在SpringBoot项目中集成（实用）

将需要发布的数据放到一个txt文件中去，需要发布某个txt文件中的数据时直接调用某个方法即可

2.2.4.1 下载相关jar包

<dependency>
            <groupId>com.github.tomakehurst</groupId>
            <artifactId>wiremock</artifactId>
            <version>2.14.0</version>
        </dependency>
        <span style="color:#0000ff;"><</span><span style="color:#800000;">dependency</span><span style="color:#0000ff;">></span>
            <span style="color:#0000ff;"><</span><span style="color:#800000;">groupId</span><span style="color:#0000ff;">></span>commons-io<span style="color:#0000ff;"></</span><span style="color:#800000;">groupId</span><span style="color:#0000ff;">></span>
            <span style="color:#0000ff;"><</span><span style="color:#800000;">artifactId</span><span style="color:#0000ff;">></span>commons-io<span style="color:#0000ff;"></</span><span style="color:#800000;">artifactId</span><span style="color:#0000ff;">></span>
            <span style="color:#0000ff;"><</span><span style="color:#800000;">version</span><span style="color:#0000ff;">></span>2.4<span style="color:#0000ff;"></</span><span style="color:#800000;">version</span><span style="color:#0000ff;">></span>
        <span style="color:#0000ff;"></</span><span style="color:#800000;">dependency</span><span style="color:#0000ff;">></span>

2.2.4.2 发布信息

》在resources目录下创建一个文件夹

》在里面创建txt文件来存放你需要发布的后台模拟数据（PS:数据要以JSON格式书写）

技巧01：一个文件只能存放一个请求对应的后台模拟数据

{
    "name": "王杨帅",
    "age": 24,
    "address": "chongqingyuzu"
    "gender": "F"
}

user.txt

》工具类

》》 WireMock连接信息配置

》》清空发布信息

》》发布工具方法

public static void mock(String filename, String url) throws IOException {
        ClassPathResource classPathResource = new ClassPathResource("mock/response/" + filename);
        String data = StringUtils.join(FileUtils.readLines(classPathResource.getFile(), "UTF-8").toArray(), "\n");
        stubFor(
                get(urlPathEqualTo(url))
                        .willReturn(
                                aResponse()
                                .withBody(data)
                                .withStatus(200)
                        )
        );
    }

发布方法

》》调用发布方法发布信息

技巧01：只需要传入文件名和请求路径即可

package com.example.wiremock.util;

import org.apache.commons.io.FileUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;

import static com.github.tomakehurst.wiremock.client.WireMock.*;

/**
 * @author 王杨帅
 * @create 2018-05-11 9:29
 * @desc
 **/
public class WireMockServerUtil {
    public static void main(String[] args) throws IOException {

        configureFor(8062);
        removeAllMappings();
        mock("user.txt", "/user");
        mock("teacher.txt", "/teacher");

    }

    public static void mock(String filename, String url) throws IOException {
        ClassPathResource classPathResource = new ClassPathResource("mock/response/" + filename);
        String data = StringUtils.join(FileUtils.readLines(classPathResource.getFile(), "UTF-8").toArray(), "\n");
        stubFor(
                get(urlPathEqualTo(url))
                        .willReturn(
                                aResponse()
                                .withBody(data)
                                .withStatus(200)
                        )
        );
    }
}

WireMockServerUtil.java

》》执行main方法进行消息发布

2.2.4.3请求WireMock中的模拟数据