Spring Data REST API集成Springfox、Swagger

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