Swagger和WireMock入门

Swagger和WireMock入门

Scroll Down

现在开发大多数都是前后端分离开发,所以自然离不开一些接口的调用,和接口文档的编写。Swagger和wiremock就是非常好的接口文档生成工具和模拟接口调用工具。

1. Swagger简介

  • 不管是前端调用后端,还是后端调用前端。都希望有一个好的接口文档,但是这个文档就跟注释一样,嘴上抱怨着别人代码不写注释,而自己最讨厌的也是写注释。使用Swagger就可以摆脱这个烦恼,只需要通过几个注解就能写出完美的接口文档。
  • 导入Swagger依赖
	<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>

  • 在启动类中通过@EnableSwagger2注解开启Swagger扫描哪些包
@SpringBootApplication
@RestController
@EnableSwagger2
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class,args);
    }
}
  • 访问路径访问Swagger界面能看到一些数据,图中框起来的部分就是我们在项目中自己书写的Controller
http://127.0.0.1:8081/swagger-ui.html

image.png

  • 打开User-Controller就能看到在Controller中书写的restful风格的接口 image.png
  • 打开getInfo这个查询指定用户的方法,我们就可以看到这个方法需要的参数,响应的具体信息。以及这个方法默认响应的状态码 image.png
  • 点击方法下边的Try it out就可以模拟发出请求,关于请求和响应的信息就会被打出来 image.png
  • 我们能发现这些接口的说明有一些缺点,比如说对应接口后边显示的是方法名,但是方法名并不能说明当前这个接口是用来做什么的。还要方法的参数我们也不知道这个参数代表的意义。这些其实都是可以通过使用注解来更改的。
  • 在Controller中使用注解更改接口文档中显示的信息
    • 现在有一个getInfo服务,我们想告诉swagger这个服务就是获取用户信息服务,只需要在方法上使用@ApiOperation(value = "用户查询服务")注解就可以更改接口显示信息
@GetMapping
    @JsonView(User.UserSimpleView.class)
    @ApiOperation(value = "用户查询服务")
    //使用UserQueryCondition接受前端传来的数据,并且使用@PageableDefault注解设置默认分页
    public List<User> query(UserQueryCondition userQueryCondition, @PageableDefault(page = 1, size = 10, sort = "username.asc") Pageable pageable) {
}
  • 再次访问swagger页面,可以看到接口文档中方法名已经换成我们自定义的接口说明了 image.png
  • 接下来我们使用注解将接口文档中的参数信息更改成我们自定义的注释
    @GetMapping("/{id:\\d+}")
    @JsonView(User.UserDetailView.class)
    public User getInfo(@ApiParam(value = "用户id") @PathVariable(value = "id") String id) {}
  • 再去看swagger页面中对应的方法,可以看到参数对应的描述变成@ApiParam(value = "用户id")中的值了 image.png

2. wiremock简介

  • 他是一个强大的模拟器,用来模拟restful风格的接口调用等。使用简单的几行代码就可以完成请求和响应。
  • 导入wiremock依赖,HTTPclient作为辅助依赖。
	<dependency>
            <groupId>com.github.tomakehurst</groupId>
            <artifactId>wiremock</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpclient</artifactId>
        </dependency>
  • 在wiremock官网上下载其jar包并运行服务端。
http://wiremock.org/docs/running-standalone/

image.png

  • 运行下载的jar包,指定端口为8082
java -jar wiremock-standalone-2.25.1.jar --port 8082

image.png

  • 启动成功之后就可以在代码中使用了,定义一个链接wiremock的客户端
/**
 * 我已经在类上直接导入wiremock的静态方法了,所以这里可以直接调用静态方法
 * import static com.github.tomakehurst.wiremock.client.WireMock.*;
 * wiremock client端。
 */
public class MockServer {
    public static void main(String[] args) throws IOException {
        configureFor(8082); //指定wiremock服务端的地址,本机就写端口
        removeAllMappings(); //清除以前的配置,把新的配置注入进去
        
    }
}

  • 启动main函数我们就已经连接上wiremock的服务端了。接下来模拟接口的调用以及响应
  • 为了方便修改响应内容,我们在resources文件夹下定义resource.mock.01.txt文件。在这个01.txt文件中就是响应的数据。 image.png
  • 我们单独写一个方法,只需要接收请求路径和需要响应的数据文件名
private static void mock(String url, String file) throws IOException {
        ClassPathResource resource = new ClassPathResource("mock/response/"+file+".txt"); //文件路径
        String content = StringUtils.join(FileUtils.readLines(resource.getFile(),"UTF-8").toArray(),"\n"); //读取文件
        stubFor(get(urlPathEqualTo(url)).willReturn(aResponse().withBody(content).withStatus(200)));
    }

  • 模拟一个请求,运行main函数,然后在浏览器中发起对应地址的请求
public static void main(String[] args) throws IOException {
        configureFor(8082); //指定wiremock服务端的地址,本机就写端口
        removeAllMappings(); //清除以前的配置,把新的配置注入进去
        mock("/order/1","01");
        mock("/order/2","02");
    }

  • 响应的数据如图 image.png

以上swagger和wiremock的入门了解就完成了。如需更多的了解请参考官方文档