資訊專欄INFORMATION COLUMN
摘要：請注意，截至目前版本，用于的集成仍處于孵化階段，并且存在一些嚴重的錯誤和缺少的功能例如，請參閱此處和此處。響應可以使用和注解來調整不同的響應狀態及其有效結論允許您在創建數據庫驅動的時產生快速結果。
原文: 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 {
// methods omitted
}
方法描述
對單個API操作的描述可以通過 @ApiOperation 注釋來修改，如下所示：
