Spring RestDocs 實戰：用單元測試自動生成優雅 API 文檔

為什麼選 Spring RestDocs？

傳統 Swagger 需在代碼中添加大量註解，侵入性強且易與實際接口脫節。Spring RestDocs 採用「測試驅動文檔」：通過 JUnit + MockMvc 執行真實請求，自動產生請求/響應片段，再由 Asciidoctor 渲染為 HTML。優勢在於：

• 文檔與測試同步，保證準確性
• 零註解污染業務代碼
• 支援多種輸出格式（HTML、PDF 等）

環境準備（15 分鐘快速上手）

• JDK 1.8+
• Maven 3.0+
• IDE（IntelliJ IDEA 推薦）

步驟 1：創建 Spring Boot 工程並引入依賴

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

步驟 2：編寫一個簡單 Controller

@RestController
public class HomeController {
    @GetMapping("/")
    public Map<String, Object> greeting() {
        return Collections.singletonMap("message", "Hello World");
    }
}

步驟 3：編寫測試類生成 Snippets

@RunWith(SpringRunner.class)
@WebMvcTest(HomeController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {
    @Autowired private MockMvc mockMvc;

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/"))
            .andDo(print())
            .andExpect(status().isOk())
            .andExpect(content().string(containsString("Hello World")))
            .andDo(document("home")); // 關鍵：生成 home 片段
    }
}

運行測試，target/snippets/home/ 下將生成：

• http-request.adoc / http-response.adoc
• curl-request.adoc / httpie-request.adoc

步驟 4：編寫 Asciidoctor 模板整合片段

創建 src/main/asciidoc/index.adoc：

= 用 Spring REST Docs 構建文檔
This is an example output for a service running at https://localhost:8080:

== Request
include::{snippets}/home/http-request.adoc[]

== Response
include::{snippets}/home/http-response.adoc[]

步驟 5：配置 asciidoctor-maven-plugin 生成 HTML

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>generate-docs</id>
      <phase>prepare-package</phase>
      <goals><goal>process-asciidoc</goal></goals>
      <configuration>
        <sourceDocumentName>index.adoc</sourceDocumentName>
        <backend>html</backend>
        <attributes>
          <snippets>${project.build.directory}/snippets</snippets>
        </attributes>
      </configuration>
    </execution>
  </executions>
</plugin>

步驟 6：一鍵生成文檔

mvnw package

輸出位於 target/generated-docs/index.html，界面簡潔、結構清晰，可直接部署發布。

進階技巧

• 字段文檔化：使用 fieldWithPath() 記錄請求/響應字段含義
• 分組標籤：tag() 將相關接口歸類
• CI/CD 集成：在流水線中自動發布文檔站點

總結

Spring RestDocs 以測試為單一事實來源，讓 API 文檔永不失真。幾分鐘接入，長期受益——強烈推薦給追求工程質量的團隊。