Swagger和Wired

柔光的暖阳◎ 2023-02-21 11:47 13阅读 0赞

> 微信公众号：**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请求的。

![format_png][]

![format_png 1][]

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

### 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其他常见注解 ###

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

### 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

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

![format_png 2][]

### 如何使用操作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)));
      }
    
    
    }

访问其相应的路径：

![format_png 3][]

查看![format_png 4][]

[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxNERYd094UUFrY2ljODZnMEk3SVVpYVZXajFwQVgwRHhuQ0FySE1zbkQzOWdUdGJZeWlicUQxVEtJWmlha2hCS2NoQ2lhVUlseWljZkJaMVVEQS82NDA?x-oss-process=image/format,png
[format_png 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxNERYd094UUFrY2ljODZnMEk3SVVpYVZXa1AxbHgxMFRST2V5UFhHR0dOTXdTRFh5RjNtQ0V5UnpzM0g3em5sMDhVaWI2b0JqS2c1alB0dy82NDA?x-oss-process=image/format,png
[format_png 2]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxNDhOd01pY2ljaWNNNmZNbG5MamliZXNzTVF6QnlKeU5RZmljdHhoeXN4dnF4eGZKb2ljVVBkQWYxVGlhaWJzVTZIZGhLRHJJRURMWW9hZUUzQVBBLzY0MA?x-oss-process=image/format,png
[format_png 3]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxNDhOd01pY2ljaWNNNmZNbG5MamliZXNzTVFxOEdpY3BQM21mallxZGZ3OENya0pEeDcwOFJUV3V5b1UyMnVYa3gzaFc0cVhGSUdzaDAxZnV3LzY0MA?x-oss-process=image/format,png
[format_png 4]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxNDhpY3BEMHpSNGphYjRpYkNDbGZ1TDF4SFJQbG41VHNxdlRpYVZOUGxSc3BucWszWFJhaWNHNFhjUlJhSW9pY3NIY1hIcko4d2dNaWFpY0ZmUkEvNjQw?x-oss-process=image/format,png