为 Spring Web API 使用 Quarkus 扩展

流程

1. 创建包含以下代码的 src/main/java/org/acme/spring/web/GreetingController.java 文件。

   src/main/java/org/acme/spring/web/GreetingController.java

   package org.acme.spring.web;
   
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/greeting")
   public class GreetingController {
   
       @GetMapping
       public String hello() {
           return "Hello Spring";
       }
   }

2. 创建包含以下代码的 src/test/java/org/acme/spring/web/GreetingControllerTest.java 文件。

   src/test/java/org/acme/spring/web/GreetingControllerTest.java

   package org.acme.spring.web;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingControllerTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/greeting")
             .then()
                .statusCode(200)
                .body(is("Hello Spring"));
       }
   
   }

流程

1. 进入项目的根目录：

   cd <project_name>

2. 使用 Quarkus Maven 插件在开发模式下运行应用程序：

   ./mvnw compile quarkus:dev

3. 导航到 http://localhost:8080/greeting 您的浏览器显示以下信息：

   Hello Spring

流程

1. 展开 GreetingController 类，如示例所示。扩展类返回 JSON 格式的响应，其中包含问候和名称。请注意，您必须从 Spring Web 导入 PathVariable 注解类，以确保您的配置正常工作：

   src/main/java/org/acme/spring/web/GreetingController.java

   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.PathVariable;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/greeting")
   public class GreetingController {
   
       @GetMapping
       public String hello() {
           return "hello";
       }
   
       @GetMapping("/{name}")
       public Greeting hello(@PathVariable(name = "name") String name) {
           return new Greeting("hello " + name);
       }
   
       public static class Greeting {
           private final String message;
   
           public Greeting(String message) {
               this.message = message;
           }
   
           public String getMessage(){
               return message;
           }
       }
   }

1. 当您更改 REST 端点时，还必须更新包含 REST 端点的单元测试的类文件：

   src/test/java/org/acme/spring/web/GreetingControllerTest.java

   package org.acme.spring.web;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingControllerTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/greeting/quarkus")
             .then()
               .statusCode(200)
               .body("message", is("hello quarkus"));
       }
   
   }

   请注意，当您在 Quarkus 中使用 Spring Web 兼容性层时，com.fasterxml:jackson.core 依赖项会自动添加到应用程序的 classpath 中，并配置。

流程

1. 输入以下命令将 quarkus-smallrye-openapi 扩展添加为 Spring Web 示例的依赖项。添加扩展足以从 REST 端点生成基本 OpenAPI 模式文档：

   ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-smallrye-openapi"

   输入命令会在 pom.xml 中添加以下依赖项：

   pom.xml

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

2. 输入以下命令从 /q/openapi 获取 schema 文档：

   curl http://localhost:8080/q/openapi

   您以 YAML 格式收到对生成的 OpenAPI 模式文档的响应：

   ---
   openapi: 3.0.3
   info:
     title: Generated API
     version: "1.0"
   paths:
     /greeting:
       get:
         responses:
           "200":
             description: OK
             content:
               text/plain:
                 schema:
                   type: string
     /greeting/{name}:
       get:
         parameters:
         - name: name
           in: path
           required: true
           schema:
             type: string
         responses:
           "200":
             description: OK
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Greeting'
   components:
     schemas:
       Greeting:
         type: object
         properties:
           message:
             type: string

流程

1. 在 GreetingController 的类级别添加 @OpenApiDefinition 注释。包括注解中的示例中显示的数据：

   @OpenAPIDefinition(
       info = @Info(
           title="Greeting API",
           version = "1.0.1",
           contact = @Contact(
               name = "Greeting API Support",
               url = "http://exampleurl.com/contact",
               email = "techsupport@example.com"),
           license = @License(
               name = "Apache 2.0",
               url = "https://www.apache.org/licenses/LICENSE-2.0.html"))
   )

2. 使用 @Tag 注释注解您的端点定义。为每个端点提供名称和描述：

   @Tag(name = "Hello", description = "Just say hello")
   @GetMapping(produces=MediaType.TEXT_PLAIN_VALUE)
   public String hello() {
       return "hello";
   }
   
   @GetMapping(value = "/{name}", produces=MediaType.APPLICATION_JSON_VALUE)
   @Tag(name = "Hello to someone", description = "Just say hello to someone")
   public Greeting hello(@PathVariable(name = "name") String name) {
       return new Greeting("hello " + name);
   }

   您在注解中提供的数据会出现在生成的 OpenAPI 模式中：

   openapi: 3.0.3
   info:
     title: Greeting API
     contact:
       name: Greeting API Support
       url: http://exampleurl.com/contact
       email: techsupport@example.com
     license:
       name: Apache 2.0
       url: https://www.apache.org/licenses/LICENSE-2.0.html
     version: 1.0.1
   tags:
   - name: Hello
       description: Just say hello
   - name: Hello to someone
       description: Just say hello to someone
   paths:
     /greeting:
       get:
         tags:
         - Hello
         responses:
           '200':
             description: OK
             content:
               text/plain:
                 schema:
                   type: string
     /greeting/{name}:
       get:
         tags:
         - Hello to someone
         parameters:
         - name: name
           in: path
           required: true
           schema:
             type: string
         responses:
           '200':
             description: OK
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Greeting'
   
   components:
     schemas:
       Greeting:
         type: object
         properties:
           message:
             type: string