Using spring restdocs to automatically generate interface documents

From: https://blog.csdn.net/a87922072/article/details/77164111

Preface

Spring REST Docs helps you to document RESTful services. It combines hand-written documentation written with Asciidoctor and auto-generated snippets produced with Spring MVC Test. This approach frees you from the limitations of the documentation produced by tools like Swagger. It helps you to produce documentation that is accurate, concise, and well-structured. This documentation then allows your users to get the information they need with a minimum of fuss. [ Spring Encyclopedias ]

start

1. Official website address- Download address , add the following configuration in pom.xml file:

  <dependencies>
    <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <version>1.2.1.RELEASE</version>
    </dependency>
</dependencies>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7

2. Add the following configuration in the plug-in. When using the maven command, the requests in the unit test will be automatically compiled into an assicdoc file:

  <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>1.5.5</version>
      <executions>
          <execution>
              <id>generate-docs</id>
              <phase>prepare-package</phase>
              <goals>
                  <goal>process-asciidoc</goal>
              </goals>
              <configuration>
                  <backend>html</backend>
                  <doctype>book</doctype>
                  <attributes>
                      <snippets>${project.build.directory}/generated-snippets</snippets>
                  </attributes>
                  <sourceDirectory>src/docs/api/asciidocs</sourceDirectory>
                  <outputDirectory>src/docs/api/html</outputDirectory>
              </configuration>
          </execution>
      </executions>
      <dependencies>
          <dependency>
              <groupId>org.springframework.restdocs</groupId>
              <artifactId>spring-restdocs-asciidoctor</artifactId>
              <version>${spring-restdoc-version}</version>
          </dependency>
      </dependencies>
  </plugin>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30

3. Unit test and document the rest api. The code is as follows

      @Test
    public void GetAllUserTest() throws Exception {

        this.mockMvc
                .perform(
                        post("/api/webchart/list")
                                .header("access_token", "2E14D92B-1FB1-4D04-8EA3-486DA78914BA")
                                .header("user_uuid", "05d44c79-627b-466c-940a-c62074107226")
                                .param("age", "1")
                )
                .andExpect(status().isOk())
                .andDo(document("1.1 Get all user interfaces",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint()),
                        requestHeaders(
                                headerWithName("access_token").description("Basic auth credentials"),
                                headerWithName("user_uuid").description("User Uuid Key")
                        ),
                        requestParameters(
                                parameterWithName("age").description("Age")
                        ),
                        responseFields(
                                fieldWithPath("code").description("0.Failure 1.Success").type(JsonFieldType.NUMBER),
                                fieldWithPath("message").description("Prompt message"),
                                fieldWithPath("userList[].id").description("user id"),
                                fieldWithPath("userList[].name").description("Full name"),
                                fieldWithPath("userList[].age").description("User password"),
                                fieldWithPath("userList[].lastActiveTime").description("Last activity time"),
                                fieldWithPath("userList[].user_name").description("User name"),
                                fieldWithPath("userList[].password").description("User password"),
                                fieldWithPath("userList[].uuid").description("user UUId")
                        )
                        )
                );
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35

4. Assemble all ADO documents together

     @Test
    public void adocBuild() throws IOException {
        String appDir = System.getProperty("user.dir");
        String adocPath = appDir + "/src/docs/api/asciidocs/apiList.adoc";
        StringBuilder content = new StringBuilder();
        content.append("include::" + appDir + "/src/docs/api/asciidocs/preview.adoc");

        File apidirs = new File(appDir + "/target/generated-snippets");
        for (File apidir : apidirs.listFiles()) {
            String apiName = apidir.getName();
            content.append("=== " + apiName + "\n\n");
            fileAppend(content, apidir + "/request-headers.adoc", "request-headers Type specification");
            fileAppend(content, apidir + "/http-request.adoc", "http-request");
            fileAppend(content, apidir + "/request-parameters.adoc", "request-parameters Type specification");
            fileAppend(content, apidir + "/request-body.adoc", "request-body Type specification");
            fileAppend(content, apidir + "/http-response.adoc", "http-response");
            fileAppend(content, apidir + "/response-fields.adoc", "response-fields Type specification");
        }
        File file = new File(adocPath);
        FileUtils.writeStringToFile(file, content.toString(), "utf-8");
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21

5. When you run the maven package command, the plug-in will convert the ADO file into an html file, which will become an offline document, Code address.

End

Attach a picture of unit test:

Tags: Spring Maven REST xml

Posted on Fri, 10 Jan 2020 07:45:34 -0800 by businessman332211