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配置保持最新的每一个细节可能使人沮丧。