API document is a necessary condition for rapid development of front-end and back-end to reduce communication costs. It is necessary to have a perfect document. The advantage of generating document by testing is that there are test data, test return results, and these fields can be explained clearly. In spring boot framework, when using mockMvc document generation, there are several following requirements. Step, uncle summed up, to share with you.

A mockMvc package reference

testCompile('org.springframework.restdocs:spring-restdocs-mockmvc')

Two snippetsDir plug-in references

plugins {
    id "org.asciidoctor.convert" version "1.5.3"
}

The address of three configurations, three paths, asciidoctor document path, generated API document directory and snippets directory

jar {
    group = 'test.lind'
    version = '0.0.1-SNAPSHOT'
    sourceCompatibility = 1.8
    dependsOn asciidoctor
    from ("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

ext {
    snippetsDir = file('build/generated-snippets')
}


integTest {
    outputs.dir snippetsDir
}


asciidoctor {
    attributes 'snippets': snippetsDir
    inputs.dir snippetsDir
    outputDir "build/asciidoc"
    dependsOn test
    sourceDir 'src/docs/asciidoc'
}

Four Added API Interfaces

@RestController
public class DocController {
  public static final String DOC = "/doc/{name}";
  public static final String DOC_LIST = "/doc/list";

  @GetMapping(DOC)
  public Map<String, String> index(@PathVariable String name) {
    Map<String, String> maps = new HashMap<>();
    maps.put("name", "Hello");
    maps.put("sex", "1");
    maps.put("buyer", name);
    return maps;
  }
}

5. Adding test cases

package test.lind.javaLindDay;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.relaxedRequestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.relaxedResponseFields;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.restdocs.payload.RequestFieldsSnippet;
import org.springframework.restdocs.payload.ResponseFieldsSnippet;
import org.springframework.restdocs.request.PathParametersSnippet;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import test.lind.javaLindDay.controller.DocController;

@ActiveProfiles("integTest")//Appoint profile Environmental Science
@RunWith(SpringRunner.class)
@WebMvcTest(DocController.class)
@AutoConfigureRestDocs(outputDir = "build/generated-snippets")
public class MockMvcTest {
  static final ResponseFieldsSnippet orderResponseFieldsParameters = relaxedResponseFields(
      fieldWithPath("name").description("Account number"),
      fieldWithPath("buyer").description("purchaser"),
      fieldWithPath("sex").description("Gender")
  );
  static final RequestFieldsSnippet orderRequestFieldsParameters = relaxedRequestFields(
      fieldWithPath("code").description("voucher no"),
      fieldWithPath("word").description("Credential word"),
      fieldWithPath("batch").description("batch")
  );
  static final PathParametersSnippet orderRequestPathParameters = pathParameters(
      parameterWithName("name").description("purchaser")
  );

  @Autowired
  private MockMvc mockMvc;

  @Test
  public void get_orders() throws Exception {
    this.mockMvc.perform(
        get(DocController.DOC, "zzl"))
        .andDo(print())
        .andExpect(status().isOk())
        .andExpect(content().string(containsString("Hello")))
        .andDo(document("doc-index", orderRequestPathParameters, orderResponseFieldsParameters));
  }

}

Here's an address to note. The package of get static method should be import static org. spring framework. restdocs. mockmvc. RestDocumentation RequestBuilders. get; otherwise, there will be no routing.

Error, this has troubled me for a long time.

Six compiles, packages, and it downloads the files required by API DOC at the same time

gradle build

Finally, go to the build/asciidoc/html 5 directory and browse our API instructions.

Thank you for reading!