与时俱进:在JAX-RS API中采用OpenAPI v3.0.0

看到时间流逝真是太恐怖了! OpenAPI规范3.0.0是对Swagger规范的重大修改,大部分已于一年前发布,但是工具赶上了一段时间。 但是,随着Swagger Core 2.0.0的最新正式发布,事情肯定会加速。

为了证明这一点,著名的JAX-RS 2.1实现Apache CXF是OpenAPI 3.0.0的最早采用者之一,在今天的帖子中,我们将了解一下JAX-RS 2.1 API可以多么容易从中受益。

与往常一样,为了使事情变得简单,我们将设计人员管理Web API,仅提供少量支持它的资源,这里没有什么太令人兴奋的。

POST   /api/people
GET    /api/people/{email}
GET    /api/people
DELETE /api/people/{email}

我们的模型将包含一个Person类。

public class Person {private String email;private String firstName;private String lastName;
}

为了增加一点魔力,我们将使用Spring Boot来使我们尽快启动并运行。 这样,让我们​​开始填充依赖项(假设我们使用Apache Maven进行构建管理)。

<dependency><groupId>org.apache.cxf</groupId><artifactId>cxf-spring-boot-starter-jaxrs</artifactId><version>3.2.4</version>
</dependency>

在最近的3.2.x版本中, Apache CXF基于Swagger Core 2.0.0引入了一个专门用于OpenAPI 3.0.0的新模块cxf-rt-rs-service-description-openapi-v3

<dependency><groupId>org.apache.cxf</groupId><artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId><version>3.2.4</version>
</dependency><dependency><groupId>org.webjars</groupId><artifactId>swagger-ui</artifactId><version>3.13.6</version>
</dependency>

Swagger UI的存在不是绝对必要的,但是它是探索API的非常有用且漂亮的工具(如果在classpath中可用, Apache CXF会将其无缝集成到您的应用程序中,我们将在稍后介绍) 。

前提条件就位,让我们做一些编码! 在开始之前,值得注意的是Swagger Core 2.0.0有很多方法可以为您的服务填充OpenAPI 3.0.0定义,包括属性文件,注释或以编程方式。 在这篇文章中,我们将仅使用注释。

@OpenAPIDefinition(info = @Info(title = "People Management API",version = "0.0.1-SNAPSHOT",license = @License(name = "Apache 2.0 License",url = "http://www.apache.org/licenses/LICENSE-2.0.html"))
)
@ApplicationPath("api")
public class JaxRsApiApplication extends Application {
}

看起来非常简单, @ OpenAPIDefinition为我们所有的Web API设置了顶级定义。 移动到PeopleRestService,我们只需添加@Tag注释,那么,标签我们的API。

@Path( "/people" ) 
@Tag(name = "people")
public class PeopleRestService {// ...
}

太棒了,到目前为止没有什么复杂的。 最棘手的部分从Web API操作定义开始,因此让我们看一下第一个示例,即获取所有人的操作。

@Produces(MediaType.APPLICATION_JSON)
@GET
@Operation(description = "List all people", responses = {@ApiResponse(content = @Content(array = @ArraySchema(schema = @Schema(implementation = Person.class))),responseCode = "200")}
)
public Collection<Person> getPeople() {// ...
}

相当多的注释,但总的来说,看起来很干净直接。 让我们看一下另一个,即通过其电子邮件地址查找此人的端点。

@Produces(MediaType.APPLICATION_JSON)
@Path("/{email}")
@GET
@Operation(description = "Find person by e-mail", responses = {@ApiResponse(content = @Content(schema = @Schema(implementation = Person.class)), responseCode = "200"),@ApiResponse(responseCode = "404", description = "Person with such e-mail doesn't exists")}
)
public Person findPerson(@Parameter(description = "E-Mail address to lookup for", required = true) @PathParam("email") final String email) {// ...
}

同样,通过电子邮件删除该人的操作看起来几乎是相同的。

@Path("/{email}")
@DELETE
@Operation(description = "Delete existing person",responses = {@ApiResponse(responseCode = "204",description = "Person has been deleted"),@ApiResponse(responseCode = "404", description = "Person with such e-mail doesn't exists")}
)
public Response deletePerson(@Parameter(description = "E-Mail address to lookup for", required = true ) @PathParam("email") final String email) {// ...
}

太好了,让我们总结一下最后一个可以说是最有趣的端点,它增加了一个新人(使用@FormParam的选择纯粹是为了说明API的不同风格)。

@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces(MediaType.APPLICATION_JSON)
@POST
@Operation(description = "Create new person",responses = {@ApiResponse(content = @Content(schema = @Schema(implementation = Person.class), mediaType = MediaType.APPLICATION_JSON),headers = @Header(name = "Location"),responseCode = "201"),@ApiResponse(responseCode = "409", description = "Person with such e-mail already exists")}
)
public Response addPerson(@Context final UriInfo uriInfo,@Parameter(description = "E-Mail", required = true) @FormParam("email") final String email, @Parameter(description = "First Name", required = true) @FormParam("firstName") final String firstName, @Parameter(description = "Last Name", required = true) @FormParam("lastName") final String lastName) {// ...
}

如果您有使用较旧的Swagger规范记录Web API的经验,那么您可能会发现该方法非常熟悉,但更为冗长(或者更确切地说 ,是形式化的)。 这是规范领导和社区所做的巨大工作的结果,以使其尽可能完整和可扩展。

已定义和记录了API,现在该尝试一下了! 不过,缺少的部分是Spring配置,在该配置中我们将初始化并公开我们的JAX-RS Web服务。

@Configuration
@EnableAutoConfiguration
@ComponentScan(basePackageClasses = PeopleRestService.class)
public class AppConfig {@Autowired private PeopleRestService peopleRestService;@Bean(destroyMethod = "destroy")public Server jaxRsServer(Bus bus) {final JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean();factory.setApplication(new JaxRsApiApplication());factory.setServiceBean(peopleRestService);factory.setProvider(new JacksonJsonProvider());factory.setFeatures(Arrays.asList(new OpenApiFeature()));factory.setBus(bus);factory.setAddress("/");return factory.create();}@Beanpublic ServletRegistrationBean cxfServlet() {final ServletRegistrationBean servletRegistrationBean = new ServletRegistrationBean(new CXFServlet(), "/api/*");servletRegistrationBean.setLoadOnStartup(1);return servletRegistrationBean;}
}

OpenApiFeature是这里的关键要素,它负责所有集成和自省。 Spring Boot应用程序是完成图片的最后一步。

@SpringBootApplication
public class Application {public static void main(String[] args) {SpringApplication.run(AppConfig.class, args);}
}

让我们立即构建并运行它:

mvn clean package 
java -jar target/jax-rs-2.1-openapi-0.0.1-SNAPSHOT.jar

启动应用程序后,我们的Web API的OpenAPI 3.0.0规范应处于活动状态,并可以JSON格式用于以下位置:

http://localhost:8080/api/openapi.json

或使用YAML格式:

http://localhost:8080/api/openapi.json

探索并使用我们的Web API会很棒吗? 由于我们包含了Swagger UI依赖关系,因此不必理会,只需导航到http:// localhost:8080 / api / api-docs?url = / api / openapi.json :

特别要注意的是,小图标Swagger UI会与您的API版本一起放置,以暗示其符合OpenAPI 3.0.0规范。

这里只需要注意,使用Spring Boot没有什么特别的。 如果您在OSGi容器中使用Apache CXF (例如,例如Apache Karaf ),则还可以与OpenAPI 3.0.0集成(如果您对此主题感兴趣,请查阅官方文档和示例 )。

一切看起来都很简单,但是如何从Swagger规范的较旧版本迁移到OpenAPI 3.0.0呢? Apache CXF具有强大的功能, 可以即时转换较旧的规范,但总的来说, OpenApi.Tools门户是评估选项的正确位置。

您应该迁移到OpenAPI 3.0.0吗? 老实说,我相信您应该,至少应该尝试进行试验,但是请注意,该工具还不够成熟,请期待一些障碍(您可以通过提供补丁来克服这些障碍) )。 但无疑,前程似锦!

完整的项目资源可在Github上找到 。

翻译自: https://www.javacodegeeks.com/2018/05/moving-with-the-times-towards-openapi-v3-0-0-adoption-in-jax-rs-apis.html

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

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

相关文章

Cpp类虚成员函数指针的用法

普通类成员函数指针 先定义一个公鸡类Cock&#xff0c;只有一个函数Shout&#xff0c;功能是输出一个字符串。 接着定义函数指针类型PFN_Shout。 main函数中代码PFN_Shout pfn_Shout &Cock::Shout;和void (Cock:: * pfn_Shout)() &Cock::Shout;的功能相同&#xf…

通过引入switch表达式来增强Java switch语句

去年12月下旬&#xff0c;我发布了“ Switch Expressions Coming Java&#xff1f; 从那时起&#xff0c;进行了广泛的讨论&#xff0c;表达了意见分歧&#xff0c;现在就Java的switch表达式的未来达成了共识。 我曾尝试在12月的博客文章中评论与switch表达式有关的一些主要发展…

jclouds_jclouds的命令行界面

jclouds序幕 我使用和为jclouds贡献了一年多的时间。 到目前为止&#xff0c;我已经在很多领域广泛使用了它&#xff0c;尤其是在Fuse生态系统中 。 它的强大之处在于它缺少一件事&#xff0c;该工具可用于管理jclouds也提供访问权限的任何云提供商。 类似于EC2命令之类的工具&…

用于从文件读取/写入字符串的新JDK 11文件方法

我之前的文章主要关注可能会添加到JDK 11中的Files.isSameContent()方法。 JDK-8201276 [“&#xff08;fs&#xff09;向文件添加方法以从文件读取字符串或向文件写入字符串”]提到了此新方法&#xff0c;并重点介绍了本文的主题&#xff1a; readString(Path) readString(P…

【数字信号处理】离散傅里叶级数(DFS)

周期信号的DFS 周期信号一定 不存在 离散傅里叶变换,通过引入冲激序列,可以进行表示,使得数学运算更加严谨;但一定存在傅里叶级数! 时域周期==>频域离散 时域离散==>频域周期 时域又离散又周期==>频域又周期又离散 联系序列的傅里叶变换DFT理解即可,只不过复指…

java对响应数据做封装_1000种对Java的响应没有死

java对响应数据做封装当一篇评论发表1000条评论时&#xff0c;值得考虑一下。 上周我的社论“ 如果Java即将死&#xff0c;它肯定看起来非常健康 ”在各个开发人员社区中都感到不安 。 在Reddit&#xff0c;Hacker News和Slashdot之间&#xff0c;它收到了1000多个评论。 奇怪…

了解自定义对象创建:JSON绑定概述系列

让我们看一下JSON绑定如何处理自定义对象的创建。 本系列的下一篇文章将介绍如何使用适配器自定义JSON-B。 JSON-B期望所有类都具有一个公共的无参数构造函数 &#xff0c;该构造函数在反序列化过程中用于实例化目标类。 创建实例后&#xff0c;可通过调用适当的setter方法或…

【数字信号处理】应用FFT计算线性卷积

线性卷积的运算量 DFT的应用方向 一是计算卷积,二是频谱分析,该博客主要讨论前者。通常,信号过系统需要计算卷积,假设 h ( n ) h(n) h(n)的长度为 N N

锁具行业电子工程师岗位职责_赏金猎人招募电子产品开发工程师产品结构工程师...

“赏金猎人”专栏6期来啦&#xff01;这个专栏&#xff0c;可以让产业需求被更广大的社区看见让社区更多有技能、有解决方案的小伙伴参与进来最终促进科技在传统产业中的应用落地专栏里面发布的猎人需求只要你觉得具备欢迎通过businesschaihuo.org跟我们取得联系今天要发布的是…

hash和hashcode_Hibernate事实:等于和HashCode

hash和hashcode每个Java对象都继承了equals和hashCode方法&#xff0c;但它们仅对Value对象有用&#xff0c;对面向无状态行为的对象没有用。 尽管使用“ ”运算符比较引用很简单&#xff0c;但是对于对象相等而言&#xff0c;事情要复杂一些。 由于您负责告诉平等性对于特定…

4代hiv检测50元_别瞧不起国货!这4个姥姥辈的护肤品,真心好用,还不到50元

在护肤这件事情上&#xff0c;其实最适合我们肤质的护肤品还是我们自己国家的生产的&#xff0c;但是国货这几年的确没有欧美的一些大牌&#xff0c;或者是日韩的护肤品更受到欢迎&#xff0c;国货被淹没的一个主要原&#xff0c;就是因为它的价格太过便宜了&#xff0c;可能老…

了解自定义De / Serializer:JSON绑定概述系列

自定义JSON绑定的最高级方法是使用自定义序列化程序和反序列化程序。 JSON-B序列化器和反序列化器是可用的最低级别的自定义&#xff0c;并且可以访问JSON处理解析器和生成器。 定制的序列化程序必须实现JsonbSerializer接口&#xff0c;并为serialise&#xff08;&#xff0…

墙面有几种装修方法_新房装修除甲醛 用这几种方法就足够

新房装修后会散发出刺鼻的有害物质&#xff0c;其中甲醛是含量最高&#xff0c;危害最大的有害气体。那怎么才能有效的去除甲醛呢?下面小编就为大家带来新房装修除甲醛的四大方法&#xff0c;希望能给大家带来帮助。新房装修除甲醛方法一&#xff1a;开窗通风法将新房的窗户打…

Parallel Parking of Truck-Trailer Using Multistage Nonlinear MPC之MATLAB simulink编译转换C++代码(内附下载地址)

引言 这个例子展示了如何使用多级非线性模型预测控制(NLMPC)来并行停放卡车-挂车系统。 在本例的应用场景中,卡车-拖车系统(EGO车辆)在停车场行驶。当停车点被定位时,非线性预测控制规划器生成停车路径。然后,自行车使用另一个非线性MPC控制器,沿着规划的路径到达目标姿态…

lambda 加和_流畅和稳定的API的Lambda

lambda 加和几周前&#xff0c;我写了关于Java 8 lambda的介绍 。 在本简介中&#xff0c;我解释了什么是lambda以及如何将它们与Java 8中也引入的新Stream API结合使用。 Stream API为集合提供了更实用的接口。 此接口在很大程度上取决于lambda。 但是&#xff0c;lambda不仅…

攻防世界 适合做桌面_空间“狭小”的二人世界,适合情侣们做浪漫的事情

在最浪漫的11月与它邂逅&#xff0c;有着深秋的枫红、累累的苹果红、还有童话绘本中的苹果屋红&#xff0c;充满着热情活力的色彩&#xff0c;让人感到雀跃。眼瞧见银河的感动。那晚入住于福寿山农场的露营区&#xff0c;位在深山中的它空气轻透又鲜少光害&#xff0c;是观赏星…

使用混合多云每个人都应避免的3个陷阱(第1部分)

每天都在肆意宣传云&#xff0c;但每个人都应避免三个陷阱。 从云&#xff0c;混合云到混合多云&#xff0c;您被告知这是确保业务数字化未来的一种方式。 您必须做出的这些选择不会排除提高客户体验和敏捷交付这些应用程序的日常工作。 让我们开始一段旅程&#xff0c;仔细研…

jquery开关灯案例_全屋开关插座布局讲解,自己规划怕遗漏,手把手教你,很详细...

开关插座是装修内重要的一环&#xff0c;然而也最容易被忽视。装修完住进来后才发现插口不够用&#xff0c;插座被家具挡住&#xff0c;想改还得砸墙&#xff0c;没办法只能用拖线板。然而&#xff0c;满屋都是拖线板&#xff0c;乱糟糟的&#xff0c;看着就惹人烦&#xff0c;…

富贵不压重发_为什么老人常说“贵人不顶重发”,“重发”是什么意思? ?...

"先&#xff0c;""贵人""在我国一般是指有身份有地位有财富的人&#xff0c;而""重发""顾名思义是指头发多的人&#xff0c;那么&#xff0c;老人们为什么会说""贵人不顶重发""呢?有书君认为&#xff0c;可…

java六大原则_六大Java功能

java六大原则我花了无数小时来对不同的应用程序进行故障排除。 通过经验&#xff0c;我可以得出关于大多数开发人员应该远离的几个Java SE功能/ API的结论。 当我提到大多数开发人员时&#xff0c;我会想到常规的Java EE开发人员&#xff0c;而不是库设计人员/基础结构工程师。…