Spring Data REST API集成Springfox、Swagger

分类: 工作日志 0人评论 assylias 4月前发布

原文: 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文档。 结果应该如下图所示。

QJHqMbcgKZc8Hur8.png

自定义输出

上图中的数字显示了一些可以自定义生成的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配置保持最新的每个细节可能令人沮丧。

上一篇:
没有了
下一篇:

你可能感兴趣的文章

0 条评论