Swagger和Wired

关注

原创最新推荐文章于 2026-08-29 14:54:19 发布 392 阅读 AI 写同款· GEO 优化 ›

超简单配置接口文档Swagger和Knife4j教程如何配置Swagger 3.0和Knife4j 3.0版本，建议使用Knife4j，因为它的前身是swagger-bootstrap-ui，是在Swagger的基础上进行了界面的优化阅读详情

微信公众号：Java患者
专注Java领域技术分享

前言

在我们前后端分离的架构中，前端与我们后端的开发是并行的，那么我们除了写自己的代码之外，我们还需要一些额外的的工具来帮助我们跟前端沟通，下面我们将为大家介绍2个常见的工具。

常见的工具

第一个就是Swagger，它可以根据我们的代码去自动生成html文档，向前端描述清楚我们的API如何去使用的，而我们后端的程序员只需要通过简单的注释，就可以不用再去写API文档了，大大减少我们维护文档的工作量。

swagger的使用

首先，我们还是要引入相关的开发包，并且在我们Spring boot的启动类上加一个注解@EnableSwagger2，这样我们的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>

我们启动好项目，访问http://localhost/swagger-ui.html就可以进入我们的swagger页面里面了，里面是我们写的Controller和Spring MVC提供的Endpoint描述，他们都是用来处理HTTP请求的。

通过默认的生成的描述，有时候我们并不能清楚的知道是怎么，比如像字段的描述，方法的作用。这时，我们可以通过注解的方法，为我们的接口文档提供更详细的信息。

swagger使用实例

@ApiOperation，方法的描述，用于方法上面，最终会代替我们的方法名称显示在文档里。

@GetMapping
@JsonView(User.UserSimpleView.class)
@ApiOperation(value = "用法查询服务")
public List<User> query(UserQueryCondition condition, Pageable pageable) {}

参数描述有2种，一种是使用对象来接收参数的描述，针对这种描述，我们只需要在字段上面加上@ApiModelProperty描述就行了。

  @ApiModelProperty("用户的名称")
  private String name;

另一种是直接使用属性去接收，使用@ApiParam描述就可以了。

@GetMapping("{id:\\d+}")
@JsonView(User.UserDetailView.class)
public User getUserInfo(@ApiParam("用户id") @PathVariable(name = "id") String id){}

Swagger其他常见注解

@Api	用在类上，说明该类的作用。
@ApiOperation	注解来给API增加方法说明。
@ApiImplicitParams	用在方法上包含一组参数说明。
@ApiImplicitParam	用来注解来给方法入参增加说明。 ‍
@ApiResponses	用于表示一组响应
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel	描述一个Model的信息
@ApiModelProperty	描述一个model的属性

WireMock的介绍

虽然Swagger可以生成我们的文档。当时使用文档总会有些和我们实际去调用服务有区别的。WireMock可以在我们后端还没开放完的情况下，给前端伪造我们的数据。

WireMock是一个独立的服务器，我们通过他的客户端来写一些java代码，来告诉服务器收到请求的时候发生什么的响应，而服务器是一直在运行，反复部署。前端只要连这个服务器就可以了，他们不用再去伪造哪些假数据了。

WireMock的使用

我们首先要去WireMock的官网去下载并安装我们的WireMock，http://wiremock.org/docs/running-standalone/。他下载后是一个jar包，我可以去jar的所在的目录上，通过下面这个命令来运行。

java -jar wiremock-standalone-2.26.3.jar --port

当看到这个界面，说明服务已经启动好了。

如何使用操作WireMock

我们需要在项目中导入我们WireMock的依赖。

<dependency>
    <groupId>com.github.tomakehurst</groupId>
    <artifactId>wiremock</artifactId>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
</dependency>

我们书写代码并运行告诉WireMock的服务器，实现收到指定请求，从指定文件读取数据并放回回去的过程。

public class MockServer {


  public static void main(String[] args) throws IOException {
      // configureFor可以指定ip和端口
    configureFor(8062);
    // 把之前所有的配置情况
    removeAllMappings();
        // 告诉我们服务器怎么处理请求。
        // url还可以写正则表达式
    mock("/order/1", "01");
    mock("/order/2", "02");
  }


  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)));
  }


}

访问其相应的路径：