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的托管位置），我们将能够看到每个响应中的链接部分。

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

 @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上找到。