摘要：請(qǐng)注意，截至目前版本，用于的集成仍處于孵化階段，并且存在一些嚴(yán)重的錯(cuò)誤和缺少的功能例如，請(qǐng)參閱此處和此處。響應(yīng)可以使用和注解來(lái)調(diào)整不同的響應(yīng)狀態(tài)及其有效結(jié)論允許您在創(chuàng)建數(shù)據(jù)庫(kù)驅(qū)動(dòng)的時(shí)產(chǎn)生快速結(jié)果。

原文: Documenting a Spring Data REST API with Springfox and Swagger

使用Spring Date REST，你可以迅速為Spring Date repositories的創(chuàng)建REST API，并提供CRUD和更多功能。然而，在嚴(yán)謹(jǐn)?shù)腁PI開(kāi)發(fā)過(guò)成功，您還希望擁有自動(dòng)生成的最新API文檔。

Code Example
本文附帶了工作示例代碼[github]()

Swagger提供了一個(gè)用于記錄REST API的規(guī)范。通過(guò)使用Springfox，我們有一個(gè)工具可以作為Spring應(yīng)用程序和Swagger之間的橋梁，為某些Spring bean和注釋創(chuàng)建一個(gè)Swagger文檔。

Springfox最近還添加了一個(gè)為Spring Data REST API創(chuàng)建Swagger文檔的功能。 這個(gè)功能還在孵化，但是我仍然玩了一下，以評(píng)估它是否可以在真實(shí)項(xiàng)目中使用。 因?yàn)槿绻沁@樣，Spring Data REST和Springfox的結(jié)合將允許快速開(kāi)發(fā)一個(gè)記錄良好的REST API。

請(qǐng)注意，截至目前（版本2.7.0），用于Spring Data REST的Springfox集成仍處于孵化階段，并且存在一些嚴(yán)重的錯(cuò)誤和缺少的功能（例如，請(qǐng)參閱此處和此處）。 因此，下面的說(shuō)明和代碼示例基于當(dāng)前的2.7.1-SNAPSHOT版本，其中可以大大改進(jìn)。

為了使Springfox能夠?yàn)槲覀兊腟pring Data REST API創(chuàng)建一個(gè)Swagger文檔，您必須執(zhí)行以下步驟。

將以下依賴項(xiàng)添加到您的應(yīng)用程序（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創(chuàng)建API文檔。

springfox-data-rest包含為Spring Data REST存儲(chǔ)庫(kù)自動(dòng)創(chuàng)建Swagger文檔的集成。

springfox-swagger-ui包含Swagger UI，它在http：// localhost：8080 / swagger-ui.html中顯示Swagger文檔

按下面的方法配置Spring Boot Application：

@SpringBootApplication
@EnableSwagger2
@Import(SpringDataRestConfiguration.class)
public class DemoApplication {
  
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
  
}

@EnableSwagger2注解通過(guò)在Spring應(yīng)用程序上下文中注冊(cè)某些bean來(lái)啟用Swagger 2支持。

@Import注釋將額外的類導(dǎo)入到Spring應(yīng)用程序上下文中，這些需要從Spring Data REST存儲(chǔ)庫(kù)自動(dòng)創(chuàng)建Swagger文檔。

你可以選擇創(chuàng)建一個(gè)Docket類型的Spring bean。 這將被Springfox拿起來(lái)配置一些swagger文檔輸出。

@Configuration
public class SpringfoxConfiguration {
  
  @Bean
  public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
      .tags(...)
      .apiInfo(...)
      ...
  }
  
}

另外可選地，您可以使用@Api，@ApiOperation和@ApiParam注釋來(lái)注釋由Spring Data REST公開(kāi)的Spring Data存儲(chǔ)庫(kù)。 以下更多細(xì)節(jié)。

最后，通過(guò)訪問(wèn)瀏覽器中的http：// localhost：8080 / swagger-ui.html，您應(yīng)該能夠查看Spring Data REST API的Swagger文檔。 結(jié)果應(yīng)該如下圖所示。

上圖中的數(shù)字顯示了一些可以自定義生成的API文檔中的東西的地方。 以下各節(jié)介紹了我認(rèn)為重要的一些定制。 你可以定制超過(guò)我發(fā)現(xiàn)的東西，所以隨時(shí)添加評(píng)論，如果你發(fā)現(xiàn)我錯(cuò)過(guò)的東西！

像標(biāo)題，描述，許可等信息可以通過(guò)創(chuàng)建一個(gè) Docket bean來(lái)配置，如上面的代碼片段，并使用其setter來(lái)更改所需的設(shè)置。

可以通過(guò)創(chuàng)建一個(gè)名稱與默認(rèn)API名稱完全相同的標(biāo)記（示例中的“地址實(shí)體”）來(lái)更改存儲(chǔ)庫(kù)的描述，并向 Docket 對(duì)象中的此標(biāo)記提供描述，并使用 @Api 將該標(biāo)記庫(kù)與該標(biāo)記庫(kù)相連接 注解。 到目前為止，我找不到修改存儲(chǔ)庫(kù)名稱的方法。

@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 {
  // methods omitted
}

對(duì)單個(gè)API操作的描述可以通過(guò) @ApiOperation 注釋來(lái)修改，如下所示：

public interface AddressRepository extends PagingAndSortingRepository {
  
  @ApiOperation("find all Addresses that are associated with a given Customer")
  Page
 findByCustomerId(@Param("customerId") Long customerId, Pageable pageable);
  
}

輸入?yún)?shù)的名稱和描述可以使用 @ApiParam 注釋進(jìn)行配置。 請(qǐng)注意，從Springfox 2.7.1開(kāi)始，參數(shù)名稱也從Spring Data提供的 @Param 注釋中讀取。

public interface AddressRepository extends PagingAndSortingRepository {
  
  Page
 findByCustomerId(@Param("customerId") @ApiParam(value="ID of the customer") Long customerId, Pageable pageable);

}

可以使用 @ApiResponses 和 @ApiResponse 注解來(lái)調(diào)整不同的響應(yīng)狀態(tài)及其有效payload：

public interface AddressRepository extends PagingAndSortingRepository {
    
  @Override
  @ApiResponses({@ApiResponse(code=201, message="Created", response=Address.class)})
  Address save(Address address);
  
}

Spring Data REST允許您在創(chuàng)建數(shù)據(jù)庫(kù)驅(qū)動(dòng)的REST API時(shí)產(chǎn)生快速結(jié)果。 Springfox允許您快速生成該API的自動(dòng)文檔。但是，由Springfox生成的API文檔與每個(gè)細(xì)節(jié)中的實(shí)際API都不匹配。一些手動(dòng)微調(diào)和注釋是必要的，如上面的定制部分所述。

一個(gè)這樣的例子是，示例請(qǐng)求和響應(yīng)的JSON在每種情況下都不能正確地呈現(xiàn)，因?yàn)镾pring Data REST使用HAL格式，Springfox僅在少數(shù)情況下使用。通過(guò)手動(dòng)工作，API文檔很難保持每個(gè)細(xì)節(jié)的最新?tīng)顟B(tài)。

我的結(jié)論是，Spring Data REST和Springfox的結(jié)合是一個(gè)很好的起點(diǎn)，可以快速生成一個(gè)REST API，它的文檔對(duì)于大多數(shù)用例來(lái)說(shuō)足夠好，特別是當(dāng)API是在一組封閉的開(kāi)發(fā)人員中開(kāi)發(fā)和使用的時(shí)候。對(duì)于公共API，細(xì)節(jié)更重要一點(diǎn)，讓Swagger注釋和Springfox配置保持最新的每個(gè)細(xì)節(jié)可能令人沮喪。