openapi开放平台架构

MicroProfile OpenAPI主要用于将OpenAPI添加到JAX-RS端点。 在这篇博客中，我们将研究SmallRye实现如何在Quarkus中使用时，通过一些额外的功能来扩展此功能，并支持更多的Web框架。

使用Quarkus

此处提供示例代码。 您也可以使用code.quarkus.io初始化项目-只需确保包括SmallRye OpenAPI扩展即可。

JAX-RS

让我们从Quarkus中的基本JAX-RS示例开始。 我们有一个Greeting对象，其中包含一条message和一个to字段，我们将为该问候创建GET ， POST和DELETE端点。

除了通常的Quarkus设置外，您还需要pom.xml的以下内容来创建JAX-RS端点：

 <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-smallrye-openapi</artifactId></dependency><dependency><groupId>io.quarkus</groupId><artifactId>quarkus-resteasy</artifactId></dependency><dependency><groupId>io.quarkus</groupId><artifactId>quarkus-resteasy-jsonb</artifactId></dependency>

在Quarkus中，您不需要Application类，我们只需添加Endpoint类：

 @Path ( "/jax-rs" )@Produces (MediaType.APPLICATION_JSON)@Consumes (MediaType.APPLICATION_JSON)public class JaxRsGreeting { @GET@Path ( "/hello" )public Greeting helloJaxRs() {return new Greeting( "Hello" , "JAX-RS" );}@POST@Path ( "/hello" )public Greeting newHelloJaxRs(Greeting greeting) {return greeting;}@DELETE@Path ( "/hello/{message}" )public void deleteHelloJaxRs( @PathParam ( "message" ) String message) {// Here do the delete.}}

到目前为止，我们还没有添加任何MicroProfile OpenAPI注释，但是由于我们添加了quarkus-smallrye-openapi扩展，因此我们已经在/openapi一个Schema文档：

 ---openapi: 3.0 . 3info:title: Generated APIversion: "1.0"paths:/jax-rs/hello:get:responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:requestBody:content:application/json:schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/jax-rs/hello/{message}:delete:parameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Contentcomponents:schemas:Greeting:type: objectproperties:message:type: stringto:type: string

有关更多信息，请参见quarkus.io/guides/rest-json 。

OpenAPI的

您可以使用MicroProfile OpenAPI将更多信息添加到生成的架构文档中。

使用配置头信息

我们添加到SmallRye的一项功能是能够添加标头信息的功能，您通常可以使用MicroProfile配置使用批注将标头信息添加到Application类。 这在不需要Application类的Quarkus中很有用。 因此，将以下内容添加到application.properties将为您提供一些标题信息：

 mp.openapi.extensions.smallrye.info.title=OpenAPI for Everyone%dev.mp.openapi.extensions.smallrye.info.title=OpenAPI for Everyone (development) %dev.mp.openapi.extensions.smallrye.info.title=OpenAPI Everyone (development)%test.mp.openapi.extensions.smallrye.info.title=OpenAPI for Everyone (test)mp.openapi.extensions.smallrye.info.version= 1.0 . 0mp.openapi.extensions.smallrye.info.description=Example on how to use OpenAPI everywheremp.openapi.extensions.smallrye.info.contact.email=phillip.kruger @redhat .commp.openapi.extensions.smallrye.info.contact.name=Phillip Krugermp.openapi.extensions.smallrye.info.contact.url=https: //www.phillip-kruger.commp.openapi.extensions.smallrye.info.license.name=Apache 2.0mp.openapi.extensions.smallrye.info.license.url=http: //www.apache.org/licenses/LICENSE-2.0.html

现在，在/openapi下/openapi生成的模式文档的/openapi ：

 ---openapi: 3.0 . 3info:title: OpenAPI for Everyone (development) title: OpenAPI Everyone (development)description: Example on how to use OpenAPI everywherecontact:name: Phillip Krugerurl: https: //www.phillip-kruger.comemail: phillip.kruger @redhat .comlicense:name: Apache 2.0url: http: //www.apache.org/licenses/LICENSE-2.0.htmlversion: 1.0 . 0 # rest of the schema document ...

向您的操作添加一些OpenAPI注释

您可以使用MicroProfile OpenAPI中的任何注释来进一步描述您的端点，例如Tag注释：

 @Path ( "/jax-rs" )@Produces (MediaType.APPLICATION_JSON)@Consumes (MediaType.APPLICATION_JSON)@Tag (name = "JAX-RS Resource" , description = "Basic Hello World using JAX-RS" )public class JaxRsGreeting {\\...}

自动生成操作ID

使用架构文档生成客户端存根的某些工具需要在架构文档中用于命名客户端存根方法的operationId 。 我们在SmallRye中添加了支持，以使用方法名称( METHOD )，类和方法名称( CLASS_METHOD )或包，类和方法名称( PACKAGE_CLASS_METHOD )自动生成此支持。 为此，将以下内容添加到application.properties ：

mp.openapi.extensions.smallrye.operationIdStrategy=METHOD

现在，您将看到operationId每个操作模式文件中：

 ---openapi: 3.0 . 3 # header omitted .../jax-rs/hello:get:tags:- JAX-RS ResourceoperationId: helloJaxRsresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- JAX-RS ResourceoperationId: newHelloJaxRsrequestBody:content:application/json:schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/jax-rs/hello/{message}:delete:tags:- JAX-RS ResourceoperationId: deleteHelloJaxRsparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content

更改OpenAPI版本

某些API网关可能需要某些OpenAPI版本才能工作。 由SmallRye扩展生成模式文档将与生成3.0.3的版本，但因为有这些版本之间只有细微的差别，您可以更改到3.0.0 ， 3.0.1或3.0.2 。 您可以通过在application.properties添加它来实现：

mp.openapi.extensions.smallrye.openapi= 3.0 . 2

现在生成的版本将是：

 ---openapi: 3.0 . 2 # Rest of the document ...

有关更多信息，请参见quarkus.io/guides/openapi-swaggerui 。

Spring网

最近在SmallRye中添加了对Spring Web的支持，这意味着，当您在Quarkus中使用Spring Web时，不仅会看到默认的OpenAPI文档，而且还可以使用MicroProfile OpenAPI进一步描述您的Spring Web端点。

让我们在当前应用程序中添加一个Spring Rest Controller。 首先将其添加到pom.xml ：

 <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-spring-web</artifactId></dependency>

现在，您可以使用Spring Web创建一个与到目前为止我们所研究的JAX-RS类似的端点：

 @RestController@RequestMapping (value = "/spring" , produces = MediaType.APPLICATION_JSON_VALUE)@Tag (name = "Spring Resource" , description = "Basic Hello World using Spring" )public class SpringGreeting { @GetMapping ( "/hello" )public Greeting helloSpring() {return new Greeting( "Hello" , "Spring" );}@PostMapping ( "/hello" )public Greeting newHelloSpring( @RequestBody Greeting greeting) {return greeting;}@DeleteMapping ( "/hello/{message}" )public void deleteHelloSpring( @PathVariable (name = "message" ) String message) { }}

Spring注释将被扫描，并将其添加到您的模式文档中：

 ---openapi: 3.0 . 3 # header omitted .../spring/hello:get:tags:- Spring ResourceoperationId: helloSpringresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- Spring ResourceoperationId: newHelloSpringrequestBody:content:'*/*' :schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/spring/hello/{message}:delete:tags:- Spring ResourceoperationId: deleteHelloSpringparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content

有关更多信息，请参见quarkus.io/guides/spring-web 。

Vert.xReact路线

在Quarkus中，您还可以使用React式路由来构建Vert.x端点。 与Spring Web相似，您的端点将在OpenAPI架构中可用，并且可以使用MicroProfile OpenAPI进行进一步描述。 要在Quarkus中添加Vert.xReact性路由，您需要在pom.xml添加以下内容：

 <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-vertx-web</artifactId></dependency>

现在您可以创建端点：

 @ApplicationScoped@RouteBase (path = "/vertx" , produces = "application/json" )@Tag (name = "Vert.x Resource" , description = "Basic Hello World using Vert.x" )public class VertxGreeting { @Route (path = "/hello" , methods = HttpMethod.GET)public Greeting helloVertX() {return new Greeting( "Hello" , "Vert.x" );}@Route (path = "/hello" , methods = HttpMethod.POST)public Greeting newHelloVertX( @Body Greeting greeting) {return greeting;}@Route (path = "/hello/:message" , methods = HttpMethod.DELETE)public void deleteHelloVertX( @Param ( "message" ) String message) { }}

现在您的Vert.x路由在OpenAPI中可用：

 ---openapi: 3.0 . 3 # header omitted .../vertx/hello:get:tags:- Vert.x ResourceoperationId: helloVertXresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- Vert.x ResourceoperationId: newHelloVertXrequestBody:content:'*/*' :schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/vertx/hello/{message}:delete:tags:- Vert.x ResourceoperationId: deleteHelloVertXparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content

有关更多信息，请参见quarkus.io/guides/reactive-routes 。

用Panache生成的端点

在Quarkus中，您可以使用Panache生成您的JAX-RS端点。 如果您在pom.xml具有quarkus-smallrye-openapi扩展名，这些生成的类也将被扫描并添加到OpenAPI模式文档中。

有关更多信息，请参见quarkus.io/guides/rest-data-panache 。

任何其他Web框架

您还可以通过在yaml文件中提供Schema文档的该部分来向文档添加任何其他端点。 举例来说，假设您有一个Servlet，它公开了一些方法，而您想将这些方法添加到架构文档中。 Servlet只是一个例子，任何Web框架都可以在这里工作。

因此，首先我们将其添加到pom.xml以在Quarkus中添加Servlet支持：

 <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-undertow</artifactId></dependency>

现在，我们可以例如创建一个Servlet端点：

 @WebServlet ( "/other/hello/*" )public class ServletGreeting extends HttpServlet { private static final Jsonb JSONB = JsonbBuilder.create(); @Overrideprotected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {response.setContentType( "application/json" );Greeting greeting = new Greeting( "Hello" , "Other" );PrintWriter out = response.getWriter();out.print(JSONB.toJson(greeting));}@Overrideprotected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {response.setContentType( "application/json" );Greeting greeting = JSONB.fromJson(request.getInputStream(), Greeting. class );PrintWriter out = response.getWriter();out.print(JSONB.toJson(greeting));}@Overrideprotected void doDelete(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {// Here do the delete}}

现在，我们需要一个映射到这些端点的OpenAPI Schema文档。 您需要将此添加到src/main/resources/META-INF名为openapi.yml的文件中：

 ---openapi: 3.0 . 3tags:- name: Other Resourcedescription: Basic Hello World using Something elsepaths:/other/hello:get:tags:- Other ResourceoperationId: helloOtherresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- Other ResourceoperationId: newHelloOtherrequestBody:content:application/json:schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/other/hello/{message}:delete:tags:- Other ResourceoperationId: deleteHelloOtherparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content

它将与其他端点合并，以显示文档中的所有路径。 因此，最后您的/openapi输出将如下所示：

 ---openapi: 3.0 . 2info:title: OpenAPI for Everyone (development) title: OpenAPI Everyone (development)description: Example on how to use OpenAPI everywherecontact:name: Phillip Krugerurl: https: //www.phillip-kruger.comemail: phillip.kruger @redhat .comlicense:name: Apache 2.0url: http: //www.apache.org/licenses/LICENSE-2.0.htmlversion: 1.0 . 0tags:- name: Other Resourcedescription: Basic Hello World using Something else- name: Spring Resourcedescription: Basic Hello World using Spring- name: JAX-RS Resourcedescription: Basic Hello World using JAX-RS- name: Vert.x Resourcedescription: Basic Hello World using Vert.xpaths:/other/hello:get:tags:- Other ResourceoperationId: helloOtherresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- Other ResourceoperationId: newHelloOtherrequestBody:content:application/json:schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/other/hello/{message}:delete:tags:- Other ResourceoperationId: deleteHelloOtherparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content/jax-rs/hello:get:tags:- JAX-RS ResourceoperationId: helloJaxRsresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- JAX-RS ResourceoperationId: newHelloJaxRsrequestBody:content:application/json:schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/jax-rs/hello/{message}:delete:tags:- JAX-RS ResourceoperationId: deleteHelloJaxRsparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content/spring/hello:get:tags:- Spring ResourceoperationId: helloSpringresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- Spring ResourceoperationId: newHelloSpringrequestBody:content:'*/*' :schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/spring/hello/{message}:delete:tags:- Spring ResourceoperationId: deleteHelloSpringparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Content/vertx/hello:get:tags:- Vert.x ResourceoperationId: helloVertXresponses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'post:tags:- Vert.x ResourceoperationId: newHelloVertXrequestBody:content:'*/*' :schema:$ref: '#/components/schemas/Greeting'responses:"200" :description: OKcontent:application/json:schema:$ref: '#/components/schemas/Greeting'/vertx/hello/{message}:delete:tags:- Vert.x ResourceoperationId: deleteHelloVertXparameters:- name: messagein: pathrequired: trueschema:type: stringresponses:"204" :description: No Contentcomponents:schemas:Greeting:type: objectproperties:message:type: stringto:type: string

它包含来自JAX-RS，Spring Web，Vert.xReact性路由和Servlet的资源。

招摇UI

在Quarkus中，默认情况下包括Swagger-UI，当您现在浏览到localhost：8080 / swagger-ui时，您将看到带有所有端点的UI：

概要

在本文中，我们研究了Quarkus如何扩展MicroProfile OpenAPI规范，以使其更易于记录端点。 我们还研究了如何使用它来记录任何Web框架。

如果您发现任何问题或有任何建议，请转到SmallRye项目，然后在此处进行讨论。

翻译自: https://www.javacodegeeks.com/2020/08/microprofile-openapi-for-everyone.html

openapi开放平台架构