原文: 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 {@Beanpublic 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 {@Beanpublic 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配置保持最新的每個細節可能令人沮喪。

總結

以上是生活随笔為你收集整理的Spring Data REST API集成Springfox、Swagger的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。