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配置保持最新的每个细节可能令人沮丧。
Spring Data REST API集成Springfox、Swagger的更多相关文章
- spring boot 基础篇 -- 集成接口测试Swagger
一.在pom.xml加入Swagger jar包引入 <dependency> <groupId>io.springfox</groupId> <artifa ...
- spring data mongo API learn(转)
显示操作mongo的语句,log4j里面加入: log4j.logger.org.springframework.data.mongodb.core=DEBUG, mongodb log4j.appe ...
- spring boot之使用springfox swagger展示restful的api doc
摘要 springfox swagger展示restful的api doc, swagger is A POWERFUL INTERFACE TO YOUR API. 新增文件: import org ...
- Spring Boot集成Springfox Swagger3和简单应用
摘要:Springfox Swagger可以动态生成 API 接口供前后端进行交互和在线调试接口,Spring Boot 框架是目前非常流行的微服务框架,所以,在Spring Boot 项目中集成Sp ...
- Spring Data Jpa 初探
Spring Data 项目的目的是为了简化构建基于 Spring 框架应用的数据访问计数,包括非关系数据库.Map-Reduce 框架.云数据服务等等;另外也包含对关系数据库的访问支持. 下载网址: ...
- spring data jpa 操作pipelinedb 的continuous view 与stream
一. 由于pipelinedb是postgreSQL的扩展,因此相关依赖于配置都合集成postgreSQL是一样的. springboot + spring data jpa + postgreSQL ...
- spring cloud 学习(10) - 利用springfox集成swagger
对绝大多数程序员而言,写接口文档是一件痛苦的事情,相对文档,他们更愿意写代码.最理想的情况就是:代码即文档!服务开发完成后,部署上去文档就自动生成,没错,这就是springfox + swagger要 ...
- 15、Spring Boot 2.x 集成 Swagger UI
1.15.Spring Boot 2.x 集成 Swagger UI 完整源码: Spring-Boot-Demos 1.15.1 pom文件添加swagger包 <swagger2.versi ...
- spring boot / cloud (三) 集成springfox-swagger2构建在线API文档
spring boot / cloud (三) 集成springfox-swagger2构建在线API文档 前言 不能同步更新API文档会有什么问题? 理想情况下,为所开发的服务编写接口文档,能提高与 ...
随机推荐
- httpclient的调用 发送json字符串
public static String postHttp(JSONObject jsonObject, String jsonUrl){ String responseMsg="" ...
- optimizer
在很多机器学习和深度学习的应用中,我们发现用的最多的优化器是 Adam,为什么呢? 下面是 TensorFlow 中的优化器, https://www.tensorflow.org/api_guide ...
- jenkins:一个jenkins项目远程触发另一个jenkins项目构建配置
很多时候,我们会有这样的应用场景:一个jenkins上的项目构建后,需要远程触发另一台机子上的jenkins中某个项目的构建,可以通过Parameterized Remote Trigger Conf ...
- JavaScript工作体系中不可或缺的函数
一.函数的概念 日常生活中,我们要完成一件事,总是习惯先有一个计划,后期按照计划,一步一步执行,则能够完成,并且达到一定效果实现一定的功能.在编程的世界里,“功能”可称呼为“函数”,因此“函数”即一段 ...
- 吴恩达机器学习笔记22-正则化逻辑回归模型(Regularized Logistic Regression)
针对逻辑回归问题,我们在之前的课程已经学习过两种优化算法:我们首先学习了使用梯度下降法来优化代价函数
- ubuntu16.04 uninstall cuda 9.0 completely and install 8.0 instead
卸载cuda 9.0sudo apt-get --purge remove cudasudo apt autoremoveto remove cuda 9.0 Thensudo apt-get cle ...
- Docker 网络背后的原理探索
本文首发于我的公众号 Linux云计算网络(id: cloud_dev),专注于干货分享,号内有 10T 书籍和视频资源,后台回复「1024」即可领取,欢迎大家关注,二维码文末可以扫. 知其然而不知其 ...
- Asp.NetCoreWebApi图片上传接口(二)集成IdentityServer4授权访问(附源码)
写在前面 本文地址:http://www.cnblogs.com/yilezhu/p/9315644.html 作者:yilezhu 上一篇关于Asp.Net Core Web Api图片上传的文章使 ...
- jvm详情——3、JVM基本垃圾回收算法回收策略
JVM基本垃圾回收算法回收策略 引用计数(Reference Counting):比较古老的回收算法.原理是此对象有一个引用,即增加一个计数,删除一个引用则减少一个计数.垃圾回收时,只用收集计数为0的 ...
- for循环中let与var的区别,块级作用域如何产生与迭代中变量i如何记忆上一步的猜想
我在前一篇讨论let与var区别的博客中,顺带一笔带过了let与var在for循环中的不同表现,虽然解释了是块级作用域的影响,但具体是怎么去影响的呢,我尝试的去理解了下,这篇博客主要从for循环步骤拆 ...