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