第 7 章 在您的 REST 控制器代码中添加 MicroProfile OpenAPI 注解

流程

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"))
   )

   Copy to Clipboard Toggle word wrap

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);
   }

   Copy to Clipboard Toggle word wrap

   您在注解中提供的数据会出现在生成的 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

   Copy to Clipboard Toggle word wrap