问题描述

　　前后端分离体系中，后端接口变动时，前端需要相应调整，但是往往没有提供详细的接口调整说明，无法开展测试。

　　拟通过编写代码并在构建后端程序时自动执行，自动生成接口文档并可查看变动情况。

　　解决方案

　　通过Junit自动执行Swagger的API获取工程后台接口信息，并将接口信息写入ShowDoc，通过ShowDoc可直观查看接口变动情况，解决接口变化感知的问题。

　　适用技术栈

　　适用于服务端，Java技术栈。

　　应用价值点和创新点

　　通过Junit自动执行Swagger的API获取工程后台接口信息，然后将获取的接口信息写入ShowDoc，每次后端程序构建时自动写入接口信息，通过ShowDoc可以查看历史接口版本并对比，解决接口变化感知的问题。

　　适用工具

　　所使用到的工具主要是Junit、Swagger（工程在线接口辅助工具）、ShowDoc，前提默认已经部署ShowDoc的测试环境。

　　ShowDoc是一款用于团队级别的在开发测试阶段在线文档分享工具，可以收集json数据并以在线文档的形式展示出来。

　　过程描述

　　总体的流程如下图所示。

图1 完整流程图

　　对工程中的每一个controller增加Swagger插件。

　　操作步骤如下：

　　（1）引入Swagger的pom文件。

      <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${swagger.version}</version>      
    </dependency>

　　（2）在启动类上增加注解。

@EnableSwagger2
@EnableFeignClients
@EnableScheduling
@SpringBootApplication
public class Init{
  public static void main(String[] args) {
    TimeZone.setDefault(TimeZone.getTimeZone("GMT+8"));
    SpringApplication.run(InitActivity.class, args);
  }
}

　　（3）在controller中增加controller的注释编写。

    @ApiOperation(value = "test", httpMethod = "POST", response = test.class, notes = "测试接口")
  @RequestMapping(value = "/test", method = RequestMethod.POST, consumes = "application/json")
  public String test(@RequestBody String reqBody）
 {}

　　编写测试用例获取工程的Swagger在线接口页面的json数据并发送给ShowDoc。操作步骤如下：

　　（1）首先，在工程中创建测试用例所在的目录和路径，如图所示。

　　这里使用的路径名称是 /src/test/java/com/test。

　　（2）编写测试类 SwaggerDocTest：

@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerDocTest {
  private MockMvc mvc;
  @Autowired
  private WebApplicationContext wac; 
  @Before
  public void getSession() throws Exception {
    mvc = MockMvcBuilders.webAppContextSetup(wac).build();
  }
    @Test
    public void createShowDoc() {
      RestTemplate client = new RestTemplate();
      String swaggerUiUrl ="http://";      //swagger的测试地址
    String apiKey ="fakekey";      //showdoc上用的参数
    String apiToken = "faketoken";    //showdoc上用的参数    
    ResultActions ra;
    String json = "";
    try {
      ra = mvc.perform(MockMvcRequestBuilders.get("/v2/api-docs")
          .contentType(MediaType.APPLICATION_JSON)
          .accept(MediaType.APPLICATION_JSON_UTF8)
          );
      ra.andExpect(MockMvcResultMatchers.status().isOk());
      ra.andDo(MockMvcResultHandlers.print());
      json = ra.andReturn().getResponse().getContentAsString();
      
    } catch (Exception e) {
      e.printStackTrace();
    }
    HttpHeaders headers = new HttpHeaders();
    HttpMethod method = HttpMethod.POST;
    headers.setContentType(MediaType.APPLICATION_JSON_UTF8);
    headers.add("Accept", MediaType.APPLICATION_JSON_UTF8.toString());
    headers.add("apiKey", apiKey);
    headers.add("apiToken", apiToken);
    String reqBody = "{\"reqBody\":"+json+"}";
    HttpEntity<String> strEntity = new HttpEntity<String>(json,headers);
//获取swagger的json数据并发送到showdoc上
    String result = 
client.postForObject("http://*****/**?swaggerUiUrl="+swaggerUiUrl, strEntity,String.class);

　　本测试类的的用处在于通过访问本工程Swagger在线接口的地址，获取Swagger在线接口页面所展示的json数据，并将此json数据发送到ShowDoc上，ShowDoc将这些json数据转换成在线接口文档并保存历史记录。

　　发布工程，并执行测试用例，使其自动更新在线接口文档，测试或者前端开发人员观看ShowDoc在线接口的历史版本信息来查看接口的变化情况。步骤如下：

　　（1）打开ShowDoc，并点击相应接口的历史版本。

　　（2）展示历史版本的变化信息。

作者：赵文涛 朱晓萌   

来源：51Testing软件测试网原创