JAX-RS和OpenAPI对Hypermedia API的支持：任重而道远

或早或晚，大多数积极使用REST（ful） Web服务和API的开发人员都偶然发现了这种真正的外星事物，即HATEOAS ： 超文本作为应用程序状态的引擎 。 对HATEOAS是什么以及它与REST的关系的好奇最终将导致发现Richardson成熟度模型 ，该模型使REST和RESTful的行业定义神秘化。 后者是一个启发，但提出了一个问题：这些年来，我们是否一直在错误地进行REST ？

让我们尝试从不同的角度回答这个问题。 HATEOAS是REST核心架构约束之一。 从这个角度来看，答案是“是”，为了声称符合REST ，Web服务或API应该支持它。 但是，如果您四处看看（甚至参考您过去或现在的经验），您可能会发现大多数Web服务和API只是域模型周围的CRUD包装器，而没有HATEOAS支持。 这是为什么？ 可能有多个原因，但是从开发人员的工具箱角度来看， HATEOAS的支持不是那么好。

在今天的帖子中，我们将讨论有关HATEOAS的 JAX-RS 2.x必须提供的内容 ，如何从服务器和客户端的角度使用它以及如何增强OpenAPI v3.0.x规范以暴露超媒体。作为合同的一部分。 如果您很兴奋，请让我们开始吧。

因此，我们的JAX-RS Web API将围绕管理公司及其员工而构建。 基础是Spring Boot和Apache CXF ，其中Swagger是OpenAPI规范的实现。 AppConfig是我们需要定义的唯一配置，以启动和运行应用程序（这要归功于Spring Boot的自动配置功能）。 

 @SpringBootConfiguration  public class AppConfig { @Bean OpenApiFeature createOpenApiFeature() { final OpenApiFeature openApiFeature = new OpenApiFeature(); openApiFeature.setSwaggerUiConfig( new SwaggerUiConfig().url( "/api/openapi.json" )); return openApiFeature; }     @Bean JacksonJsonProvider jacksonJsonProvider() { return new JacksonJsonProvider(); }  }

Company和Person这个模型非常简单（请注意，这两个类之间没有直接关系）。 

 public class Company { private String id; private String name;  }  public class Person { private String id; private String email; private String firstName; private String lastName;  }

该模型通过CompanyResource公开， CompanyResource是典型的JAX-RS资源类，带有@Path注释，此外还带有OpenAPI的@Tag注释。 

 @Component  @Path ( "/companies" )  @Tag (name = "companies" )  public class CompanyResource { @Autowired private CompanyService service;  }

很好，资源类尚未定义端点，因此让我们加强一下。 我们的第一个端点将通过标识符查找公司，并以JSON格式返回其表示形式。 但是，由于我们没有包含任何与员工相关的细节，因此提示消费者（Web UI或任何其他客户端）在哪里查找真是太棒了。 有多种方法可以执行此操作，但是由于我们坚持使用JAX-RS ，因此可以使用开箱即用的Web链接 （ RFC-5988 ）。 该代码段包含数千个单词。 

 @Produces (MediaType.APPLICATION_JSON)  @GET  @Path ( "{id}" )  public Response getCompanyById( @Context UriInfo uriInfo, @PathParam ( "id" ) String id) { return service .findCompanyById(id) .map(company -> Response .ok(company) .links( Link.fromUriBuilder(uriInfo .getRequestUriBuilder()) .rel( "self" ) .build(), Link.fromUriBuilder(uriInfo .getBaseUriBuilder() .path(CompanyResource. class )) .rel( "collection" ) .build(), Link.fromUriBuilder(uriInfo .getBaseUriBuilder() .path(CompanyResource. class ) .path(CompanyResource. class , "getStaff" )) .rel( "staff" ) .build(id) ) .build()) .orElseThrow(() -> new NotFoundException( "The company with id '" + id + "' does not exists" ));  }

这里几乎没有发生任何事情。 我们关心的是使用ResponseBuilder :: links方法，其中提供了三个链接。 第一个是self ，它本质上是链接上下文（定义为RFC-5988的一部分）。 第二个是collection ，它指向CompanyResource端点，该端点返回公司列表（也包含在标准关系注册表中）。 最后，第三个是我们自己的员工关系，我们通过一个名为getStaff的方法实现的另一CompanyResource端点组装（我们将看到它不久）。 这些链接将在“ 链接”响应标头中传递，并指导客户端下一步去向。 让我们通过运行该应用程序来实际查看它。 

 $ mvn clean package  $ java -jar target/jax-rs- 2.1 -hateaos- 0.0 . 1 -SNAPSHOT.jar

然后使用curl检查来自此资源端点的响应（不必要的详细信息已被滤除）。 

 $ curl -v http: //localhost:8080/api/companies/1  > GET /api/companies/ 1 HTTP/ 1.1  > Host: localhost: 8080  > User-Agent: curl/ 7.47 . 1  > Accept: */*  >  < HTTP/ 1.1 200  < Link: <http: //localhost:8080/api/companies/1>;rel="self"  < Link: <http: //localhost:8080/api/companies/1/staff>;rel="staff"  < Link: <http: //localhost:8080/api/companies>;rel="collection"  < Content-Type: application/json  < Transfer-Encoding: chunked  <  { "id" : "1" , "name" : "HATEOAS, Inc."  }

链接头在那里，指的是其他感兴趣的端点。 从客户的角度来看，事情看起来也很简单。 Response类提供专用的getLinks方法来包装对Link响应标头的访问，例如： 

 final Client client = ClientBuilder.newClient();  try ( final Response response = client .target( " http://localhost:8080/api/companies/ {id}" ) .resolveTemplate( "id" , "1" ) .request() .accept(MediaType.APPLICATION_JSON) .get()) {             final Optional staff = response .getLinks() .stream() .filter(link -> Objects.equals(link.getRel(), "staff" )) .findFirst();             staff.ifPresent(link -> { // follow the link here });  } finally { client.close();  }

到目前为止，一切都很好。 展望未来，由于HATEOAS本质上是Web API合同的一部分，因此让我们在桌上找出OpenAPI规范所具有的内容。 不幸的是， 到目前为止 尚不支持 HATEOAS ，但是从好的方面来说，存在链接的概念（尽管不应将它们与Web链接混淆，它们有些相似，但并不相同）。 为了说明作为OpenAPI规范一部分的链接的用法，让我们用Swagger注释装饰端点。 

 @Operation ( description = "Find Company by Id" , responses = { @ApiResponse ( content = @Content (schema = @Schema (implementation = Company. class )), links = { @io .swagger.v3.oas.annotations.links.Link( name = "self" , operationRef = "#/paths/~1companies~1{id}/get" , description = "Find Company" , parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" ) ), @io .swagger.v3.oas.annotations.links.Link( name = "staff" , operationRef = "#/paths/~1companies~1{id}~1staff/get" , description = "Get Company Staff" , parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" ) ), @io .swagger.v3.oas.annotations.links.Link( name = "collection" , operationRef = "#/paths/~1companies/get" , description = "List Companies" ) }, description = "Company details" , responseCode = "200" ), @ApiResponse ( description = "Company does not exist" , responseCode = "404" ) }  )  @Produces (MediaType.APPLICATION_JSON)  @GET  @Path ( "{id}" )  public Response getCompanyById( @Context UriInfo uriInfo, @PathParam ( "id" ) String id) { // ...  }

如果我们运行该应用程序并浏览到浏览器中的http：// localhost：8080 / api / api-docs （这是Swagger UI的托管位置），我们将能够看到每个响应中的链接部分。

超媒体API

但是除此之外……您可以使用那里的链接做很多事情（如果您对该主题感兴趣，请注意此问题 ）。 吸引公司员工的资源终点看起来非常相似。 

 @Operation ( description = "Get Company Staff" , responses = { @ApiResponse ( content = @Content (array = @ArraySchema (schema = @Schema (implementation = Person. class ))), links = { @io .swagger.v3.oas.annotations.links.Link( name = "self" , operationRef = "#/paths/~1companies~1{id}~1staff/get" , description = "Staff" , parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" ) ), @io .swagger.v3.oas.annotations.links.Link( name = "company" , operationRef = "#/paths/~1companies~1{id}/get" , description = "Company" , parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" ) ) }, description = "The Staff of the Company" , responseCode = "200" ), @ApiResponse ( description = "Company does not exist" , responseCode = "404" ) }  )  @Produces (MediaType.APPLICATION_JSON)  @GET  @Path ( "{id}/staff" )  public Response getStaff( @Context UriInfo uriInfo, @PathParam ( "id" ) String id) { return service .findCompanyById(id) .map(c -> service.getStaff(c)) .map(staff -> Response .ok(staff) .links( Link.fromUriBuilder(uriInfo .getRequestUriBuilder()) .rel( "self" ) .build(), Link.fromUriBuilder(uriInfo .getBaseUriBuilder() .path(CompanyResource. class ) .path(id)) .rel( "company" ) .build() ) .build()) .orElseThrow(() -> new NotFoundException( "The company with id '" + id + "' does not exists" ));  }

如您所料，除了指向self的链接之外，它还包括指向公司的链接。 当我们使用curl尝试时，预期的响应标头将返回。 

 $ curl -v http: //localhost:8080/api/companies/1/staff  > GET /api/companies/ 1 /staff HTTP/ 1.1  > Host: localhost: 8080  > User-Agent: curl/ 7.47 . 1  > Accept: */*  >  < HTTP/ 1.1 200  < Link: <http: //localhost:8080/api/companies/1/staff>;rel="self"  < Link: <http: //localhost:8080/api/companies/1>;rel="company"  < Content-Type: application/json  < Transfer-Encoding: chunked  <  [ { "id" : "1" , "email" : "john@smith.com" , "firstName" : "John" , "lastName" : "Smith" }, { "id" : "2" , "email" : "bob@smith.com" , "firstName" : "Bob" , "lastName" : "Smith" }  ]

那么我们可以得出什么样的结论呢？ HATEOAS实际上通过动态地驱动对话来统一Web API提供者和使用者之间的交互模型。 这非常强大，但是其中的大多数框架和工具要么都对HATEOAS提供了相当基本的支持（例如Web Linking ），要么根本没有。

在很多情况下，只要使用Web链接就足够了（到目前为止，我们已经看到了示例，例如分页，导航等），但是假设创建，编辑或修补现有资源又如何呢？ 如何用超媒体丰富集合中返回的各个元素（在RFC-6537中进行描述）？ HATEOAS是否值得所有这些努力？

与往常一样，答案是“取决于”，也许我们应该超越JAX-RS ？ 在下一篇文章中（s_，我们将继续解决问题。

完整的源代码可在Github上找到 。

翻译自: https://www.javacodegeeks.com/2019/02/hypermedia-apis-support-jax-rs-openapi.html

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/343565.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

工业以太网交换机的光口和电口有什么区别？

工业以太网交换机的光口和电口有什么区别？

对于从事安防传输设备行业的朋友们来说&#xff0c;相信大家对工业以太网交换机应该都不陌生。客户购买工业以太网交换机时&#xff0c;很多客户都会要几光几电的交换机&#xff0c;最近也接到不少客户的电话&#xff0c;都会询问工业以太网交换机的电口和光口有什么区别&#…
阅读更多...
家用、商用、工业交换机的用途与区别

家用、商用、工业交换机的用途与区别

以太网交换机一般分为&#xff1a;商用(以太网)交换机、工业(以太网)交换机、家用(以太网)交换机。那么&#xff0c;家用交换机&#xff0c;商业交换机&#xff0c;工业交换机之间有什么区别呢&#xff1f;接下来我们就跟随飞畅科技的小编一起来详细了解下吧&#xff01; 商用…
阅读更多...
将Spring Boot应用程序部署到Tomcat中

将Spring Boot应用程序部署到Tomcat中

“我喜欢编写身份验证和授权代码。” 〜从来没有Java开发人员。 厌倦了一次又一次地建立相同的登录屏幕&#xff1f; 尝试使用Okta API进行托管身份验证&#xff0c;授权和多因素身份验证。 部署应用程序很困难。 通常&#xff0c;您需要控制台访问服务器&#xff0c;从服务器…
阅读更多...
HD-SDI光端机是什么？其性能特点和技术参数有哪些？

HD-SDI光端机是什么？其性能特点和技术参数有哪些？

HD-SDI光端机是将SDI信号与光信号互相转换的设备。SDI光端机的原理是发送端将SDI信号通过激光器调制后变为光信号,接收端将激光二极管收到的数据再编码为SDI信号。那么&#xff0c;HD-SDI光端机是什么呢&#xff1f;其性能特点和技术参数有哪些呢&#xff1f;接下来我们就跟随飞…
阅读更多...
HD-SDI光端机有哪些优势？

HD-SDI光端机有哪些优势？

3G-SDI光端机适合电视行业的高清可靠、高清性能的标准&#xff0c;杭州飞畅的3G-SDI光端机采用最新科技&#xff0c;采用H.264编码方式&#xff0c;采用高清SDI专用VIDIO SFP光模块&#xff0c;一般情况下采用SDI接口。其产品最早为广电行业客户开发使用&#xff0c;应用于电视…
阅读更多...
PDH-SDH光端机指示灯具体含义介绍

PDH-SDH光端机指示灯具体含义介绍

最近有很多客户朋友来咨询有关PDH/SDH光端机各个指示灯含义的问题&#xff0c;其实在很多故障发生的时候我们都可以通过光端机各个指示灯的状态来分析故障问题&#xff0c;从而帮助解决问题。接下来我们就来为大家详细介绍一下PDH/SDH光端机指示灯的具体含义&#xff0c;感兴趣…
阅读更多...
PDH光端机的主要作用以及特点有哪些？

PDH光端机的主要作用以及特点有哪些？

在之前小编为大家介绍了光端机的详细分类&#xff0c;相信很多看过的朋友对pdh光端机这一块不陌生了吧&#xff0c;但是对于pdh光端机的作用以及特点你还了解吗&#xff0c;今天&#xff0c;飞畅科技的小编就来为大家详细介绍下pdh光端机的作用以及特点&#xff0c;感兴趣的朋友…
阅读更多...
python将html存为pdf_用Python将HTML转为PDF。

python将html存为pdf_用Python将HTML转为PDF。

上期提到了如何获取公众号文章信息&#xff0c;这回就说下怎么将网页转为PDF&#xff0c;方便日常学习。html而后扩散一下以前一个比赛的结果(华章计算机抖音大赛)。数据库顺便谈谈本身对从此送书的一个想法。微信另外以前的送书活动&#xff0c;有中奖的读者没有联系我&#x…
阅读更多...
使用Gradle – 2019版从Travis可靠发布到Maven Central

使用Gradle – 2019版从Travis可靠发布到Maven Central

得益于在2018年和2019年末实现的显式登台存储库创建功能集&#xff0c;使您&#xff08;自动&#xff09;从Travis&#xff08;不仅是&#xff09;发布到Maven Central更加可靠。 背景 如果您仅想获取信息&#xff0c;如何使您的工件从Travis发布更可靠&#xff0c;请前进到另…
阅读更多...
spring admin mysql_easyadmin: 简易的java后台管理框架，基于SpringBoot+FreeMark+ace admin+mysql...

spring admin mysql_easyadmin: 简易的java后台管理框架，基于SpringBoot+FreeMark+ace admin+mysql...

easyadmin数据库一定要用utf8mb4编码&#xff0c;记得先执行manager.sql&#xff0c;再执行initdata.sql,其中tenant表不用管&#xff0c;这是我打算做的另外一个项目设计的表&#xff0c;因为直接复制的本项目&#xff0c;怕到时候忘记&#xff0c;所以没有删除拦截器相关文档…
阅读更多...
SDI高清视频光端机特点有哪些？

SDI高清视频光端机特点有哪些？

SDI视频光端机设计和生产是适用于电视行业的高可靠、高性能的串行数字光传输设备&#xff0c;信号格式从19.4Mbps到1.485Gbps, 系统支持SMPTE292、SMPTE259M、SMPTE297M、SMPTE305M、SMPTE310M以及DVB-ASI(EN50083-9)等数字电视格式的信号,满足工业级产品的要求。那么&#xff…
阅读更多...
SDI光端机是什么？SDI光端机产品介绍及监控方案！

SDI光端机是什么？SDI光端机产品介绍及监控方案！

SDI光端机就是光信号传输的中端设备。光纤价格的降低使它在各个领域得到很好的应用&#xff0c;因此各个光端机的厂家就好比是雨后春笋般发展起来。但是这里的厂家大部分技术并不是完全成熟&#xff0c;开发新技术需要耗资和人力、物力等&#xff0c;这就产生厂家多是中小企业&…
阅读更多...
adf可以自定义溶剂吗_ADF Faces。 立即的自定义客户端事件

adf可以自定义溶剂吗_ADF Faces。 立即的自定义客户端事件

adf可以自定义溶剂吗在本文中&#xff0c;我将重点介绍ADF Faces Javascript API方法以从客户端触发自定义事件。 例如&#xff1a; function cliListener(actionEvent) {AdfCustomEvent.queue(actionEvent.getSource(), "servListener",null, true);}我们可以使用a…
阅读更多...
VGA光端机技术原理及应用领域介绍

VGA光端机技术原理及应用领域介绍

VGA光端机采用纯数字传输模式&#xff0c;能从根本上克服普通铜芯电缆传输系统在传输高频带信号时造成的拖尾、重影等现象&#xff0c;清晰的重现图象画面。VGA光端机传输的是光信号&#xff0c;没有电磁辐射&#xff0c;系统具有极高的保密性。同时VGA光端机把显示设备和信号源…
阅读更多...
java getbytes 长度_JAVA中的getBytes()方法

java getbytes 长度_JAVA中的getBytes()方法

在Java中&#xff0c;String的getBytes()方法是得到一个操作系统默认的编码格式的字节数组。这个表示在不同情况下&#xff0c;返回的东西不一样&#xff01;String.getBytes(String decode)方法会根据指定的decode编码返回某字符串在该编码下的byte数组表示&#xff0c;如&…
阅读更多...
按应用领域来划分，电话光端机主要分为哪几类

按应用领域来划分，电话光端机主要分为哪几类

我们都知道&#xff0c;电话光端机就是把传统的电话信号转换成光信号并在光纤上进行传输的设备。但是对于电话光端机的分类这块&#xff0c;大家可能了解的并不是很清楚&#xff0c;电话光端机根据不同的分类方式&#xff0c;有着不同的分法&#xff0c;今天飞畅科技的小编主要…
阅读更多...
光纤收发器长距离的传输过程出现死机的解决方案

光纤收发器长距离的传输过程出现死机的解决方案

光纤收发器是网络通信中必不可少的一种设备&#xff0c;但是&#xff0c;我们在使用过程中难免会遇到各种各样的问题&#xff0c;其中&#xff0c;光纤收发器出现死机可以说是很常见的一种故障&#xff0c;那么&#xff0c;光纤收发器经常会出现死机到底是什么原因&#xff0c;…
阅读更多...
什么是光纤收发器？光纤收发器的两种连接方案你了解吗？

什么是光纤收发器？光纤收发器的两种连接方案你了解吗？

在如今这个科技飞速发展的时代&#xff0c;网络变得越来越重要&#xff0c;而说到网络的发展和建设&#xff0c;那就离不开光纤的大量应用了&#xff0c;怎样才能在网络建设中更快更稳定的实现光信号与电信号的相互转换&#xff0c;是我们要考虑的一个重要问题。而光纤收发器正…
阅读更多...
maven项目 ant_将旧项目从Ant迁移到Maven的4个简单步骤

maven项目 ant_将旧项目从Ant迁移到Maven的4个简单步骤

maven项目 ant一段时间以来&#xff0c;我们一直在考虑将构建从蚂蚁移植到Maven。 它发生在上个月&#xff0c;实际上比我们预期的要简单。 根据我的经验&#xff0c;这里简要介绍了我们遵循的步骤。 我们的应用程序是一个具有多个框架和技术的企业Web应用程序构建&#xff0c;…
阅读更多...
工业级千兆以太网光纤收发器产品介绍

工业级千兆以太网光纤收发器产品介绍

工业级光纤收发器是一种可以延长传输距离的一种工业交换机&#xff0c;它具有便捷、维护简单、抗干扰性能强、性能强大、运行稳定等优点。产品设计符合以太网标准&#xff0c;性能稳定可靠。该设备可广泛应用于智能交通、电信、安防、金融证券、海关、海运、电力、水利及油田等…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023