原文: Documenting a Spring Data REST API with Springfox and Swagger
使用Spring Date REST，你可以迅速為Spring Date repositories的創建REST API，並提供CRUD和更多功能。然而，在嚴謹的API開發過成功，您還希望擁有自動生成的最新API文檔。
Code Example
本文附帶了工作示例代碼github
Swagger提供了一個用於記錄REST API的規范。通過使用Springfox，我們有一個工具可以作為Spring應用程序和Swagger之間的橋梁，為某些Spring bean和注釋創建一個Swagger文檔。
Springfox最近還添加了一個為Spring Data REST API創建Swagger文檔的功能。 這個功能還在孵化，但是我仍然玩了一下，以評估它是否可以在真實項目中使用。 因為如果是這樣，Spring Data REST和Springfox的結合將允許快速開發一個記錄良好的REST API。
請注意，截至目前（版本2.7.0），用於Spring Data REST的Springfox集成仍處於孵化階段，並且存在一些嚴重的錯誤和缺少的功能（例如，請參閱此處和此處）。 因此，下面的說明和代碼示例基於當前的2.7.1-SNAPSHOT版本，其中可以大大改進。
在Spring Boot / Spring Data REST應用程序中啟用Springfox
為了使Springfox能夠為我們的Spring Data REST API創建一個Swagger文檔，您必須執行以下步驟。
添加Springfox依賴
將以下依賴項添加到您的應用程序（gradle）中：
compile('io.springfox:springfox-swagger2:2.7.0') compile('io.springfox:springfox-data-rest:2.7.0') compile('io.springfox:springfox-swagger-ui:2.7.0')springfox-swagger2包含Springfox的核心功能，允許使用Swagger 2創建API文檔。springfox-data-rest包含為Spring Data REST存儲庫自動創建Swagger文檔的集成。springfox-swagger-ui包含Swagger UI，它在http：// localhost：8080 / swagger-ui.html中顯示Swagger文檔
配置Application
按下面的方法配置Spring Boot Application：
@SpringBootApplication @EnableSwagger2 @Import(SpringDataRestConfiguration.class) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }@EnableSwagger2注解通過在Spring應用程序上下文中注冊某些bean來啟用Swagger 2支持。@Import注釋將額外的類導入到Spring應用程序上下文中，這些需要從Spring Data REST存儲庫自動創建Swagger文檔。
創建Docket bean
你可以選擇創建一個Docket類型的Spring bean。 這將被Springfox拿起來配置一些swagger文檔輸出。
@Configuration public class SpringfoxConfiguration { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .tags(...) .apiInfo(...) ... } }Spring Data repositories添加注解
另外可選地，您可以使用@Api，@ApiOperation和@ApiParam注釋來注釋由Spring Data REST公開的Spring Data存儲庫。 以下更多細節。
輸出
最后，通過訪問瀏覽器中的http：// localhost：8080 / swagger-ui.html，您應該能夠查看Spring Data REST API的Swagger文檔。 結果應該如下圖所示。
自定義輸出
上圖中的數字顯示了一些可以自定義生成的API文檔中的東西的地方。 以下各節介紹了我認為重要的一些定制。 你可以定制超過我發現的東西，所以隨時添加評論，如果你發現我錯過的東西！
通用的API信息
像標題，描述，許可等信息可以通過創建一個 Docket bean來配置，如上面的代碼片段，並使用其setter來更改所需的設置。
Repository描述
可以通過創建一個名稱與默認API名稱完全相同的標記（示例中的“地址實體”）來更改存儲庫的描述，並向 Docket 對象中的此標記提供描述，並使用 @Api 將該標記庫與該標記庫相連接 注解。 到目前為止，我找不到修改存儲庫名稱的方法。
@Configuration public class SpringfoxConfiguration { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .tags(new Tag("Address Entity", "Repository for Address entities")); } } @Api(tags = "Address Entity") @RepositoryRestResource(path = "addresses") public interface AddressRepository extends CrudRepository<Address, Long> { // methods omitted }方法描述
對單個API操作的描述可以通過 @ApiOperation 注釋來修改，如下所示：
public interface AddressRepository extends PagingAndSortingRepository<Address, Long> { @ApiOperation("find all Addresses that are associated with a given Customer") Page<Address> findByCustomerId(@Param("customerId") Long customerId, Pageable pageable); }輸入參數
輸入參數的名稱和描述可以使用 @ApiParam 注釋進行配置。 請注意，從Springfox 2.7.1開始，參數名稱也從Spring Data提供的 @Param 注釋中讀取。
public interface AddressRepository extends PagingAndSortingRepository<Address, Long> { Page<Address> findByCustomerId(@Param("customerId") @ApiParam(value="ID of the customer") Long customerId, Pageable pageable); }響應
可以使用 @ApiResponses 和 @ApiResponse 注解來調整不同的響應狀態及其有效payload：
public interface AddressRepository extends PagingAndSortingRepository<Address, Long> { @Override @ApiResponses({@ApiResponse(code=201, message="Created", response=Address.class)}) Address save(Address address); }結論
Spring Data REST允許您在創建數據庫驅動的REST API時產生快速結果。 Springfox允許您快速生成該API的自動文檔。但是，由Springfox生成的API文檔與每個細節中的實際API都不匹配。一些手動微調和注釋是必要的，如上面的定制部分所述。
一個這樣的例子是，示例請求和響應的JSON在每種情況下都不能正確地呈現，因為Spring Data REST使用HAL格式，Springfox僅在少數情況下使用。通過手動工作，API文檔很難保持每個細節的最新狀態。
我的結論是，Spring Data REST和Springfox的結合是一個很好的起點，可以快速生成一個REST API，它的文檔對於大多數用例來說足夠好，特別是當API是在一組封閉的開發人員中開發和使用的時候。對於公共API，細節更重要一點，讓Swagger注釋和Springfox配置保持最新的每個細節可能令人沮喪。