【譯】Spring 官方教程：使用 Restdocs 建立 API 文檔

原文：Creating API Documentation with Restdocs

譯者：HoldDie

校對：Jitianyu

本指南將引導你瞭解在 Spring 應用程式中為 HTTP 端點（HTTP endpoints）產生文檔的過程。 你會建立什麼

你將構建一個簡單的 Spring 應用程式，其中包含一些暴露 API 的 HTTP 端點（HTTP endpoints）。你將使用 Spring MockMVC 以及 JUnit 來進行 Web 層測試，然後你將使用相同的測試，來為使用 [Spring REST Docs] 的 API 產生文檔。 你需要什麼

約 15 分鐘

最喜歡的文字編輯器或IDE

JDK 1.8 或更高版本

Gradle 2.3+ 或 Maven 3.0+

你還可以將代碼直接匯入到IDE中：

Spring Tool Suite (STS)

IntelliJ IDEA 如何完成本指南

與大多數“ 入門指南 ”一樣，你可以從頭開始，完成每一步，也可以繞過已經熟悉的基本設定步驟。無論哪種方式，你都會得到可以成功啟動並執行代碼。

要從頭開始，請跳轉到使用 Gradle構建。

要跳過基本操作，請執行以下操作：

下載 並解壓縮本指南的原始碼庫，或使用 Git 複製它： git clone https://github.com/spring-guides/gs-testing-restdocs.git

cd進入 gs-testing-restdocs/initial

跳轉到 建立一個簡單的應用程式 。

完成後，你可以根據代碼檢查結果 gs-testing-restdocs/complete。 使用 Gradle 構建

第一步，建立基本的構建指令碼（build script）。 當使用 Spring 構建 apps 的時候，幾乎可以使用任何你喜歡的構建工具， 但是此指南只介紹了如何使用 Gradle 和 Maven 來構建目標 app。如果這兩個工具你都不熟悉，請參考 Building Java Projects with Gradle 或 Building Java Projects with Maven。 建立目錄結構

在你選擇的項目目錄中，建立以下子目錄結構。例如，在 *nix 系統中使用命令 mkdir-p src/main/java/hello 來建立該目錄結構。

                  
└── src           
    └── main          
        └── java           
            └── hello        

建立一個Gradle構建檔案

以下是 初始化的Gradle構建檔案。

build.gradle

                  
buildscript {          
    repositories {          
        mavenCentral()          
    }          
    dependencies {          
        classpath("org.springframework.boot:spring-boot-gradle-plugin:1.4.0.RELEASE")          
    }          
}          
          
apply plugin: 'java'          
apply plugin: 'eclipse'          
apply plugin: 'idea'          
apply plugin: 'spring-boot'