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