Java Enum 上的 OpenAPI 和 @Schema 注释

Posted 2023-03-28

【中文标题】Java Enum 上的 OpenAPI 和 @Schema 注释

【英文标题】：OpenAPI and @Schema annotation on Java Enum

【发布时间】：2019-07-08 09:06:54

【问题描述】：

我正在从带注释的 Java 代码生成 OpenAPI 3.0 文档。但问题是，当我将 @Schema 注释添加到枚举时，所有值都消失了。我正在使用带有 microprofile-openapi 分数的 Thorntail 2.3.0.Final。

我知道我可以只更改 .yaml 文件，但我需要直接从 Java 代码生成我的 yaml。

这是我在 github 上的最小示例： https://github.com/pkristja/openApiEnumSchema

枚举源代码：

package com.example.openapiexample.model;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonValue;
import org.eclipse.microprofile.openapi.annotations.media.Schema;

@Schema(description = "<div class=\\\"renderedMarkdown\\\"><p>Rank of developer.</p>\\n\" +\n" +
        "        \"<p>Valid values are:</p>\\n\" +\n" +
        "        \"<ul>\\n\" +\n" +
        "        \"<li>'JUNIOR_DEVELOPER_1': Text for junior 1.\\n\" +\n" +
        "        \"<li>'JUNIOR_DEVELOPER_2': Text for junior 2.\\n\" +\n" +
        "        \"<li>'JUNIOR_DEVELOPER_3': Text for junior 3.\\n\" +\n" +
        "        \"<li>'SENIOR_DEVELOPER_1': Text for senior 1.\\n\" +\n" +
        "        \"<li>'SENIOR_DEVELOPER_2': Text for senior 1.\\n\" +\n" +
        "        \"<li>'SENIOR_DEVELOPER_3': Text for senior 1.\\n\" +\n" +
        "        \"</ul>\\n\" +\n" +
        "        \"<p>Random text...\\n\" +\n" +
        "        \"and has to be added to this API definition as well.</p></div>",
        enumeration = "junior_developer_1", "junior_developer_2", "junior_developer_3",
                "senior_developer_1", "senior_developer_2", "senior_developer_3")
public enum Rank 
    JUNIOR_DEVELOPER_1("junior_developer_1"),
    JUNIOR_DEVELOPER_2("junior_developer_2"),
    JUNIOR_DEVELOPER_3("junior_developer_3"),
    SENIOR_DEVELOPER_1("senior_developer_1"),
    SENIOR_DEVELOPER_2("senior_developer_2"),
    SENIOR_DEVELOPER_3("senior_developer_3");

    private String value;

    Rank(String value) 
        this.value = value;
    

    @Override
    @JsonValue
    public String toString() 
        return String.valueOf(value);
    

    @JsonCreator
    public static Rank fromValue(String text) 
        for (Rank b : Rank.values()) 
            if (String.valueOf(b.value).equals(text)) 
                return b;
            
        
        return null;
    

Object 的源代码包括枚举：

package com.example.openapiexample.model;

import lombok.Data;
import org.eclipse.microprofile.openapi.annotations.media.Schema;

@Data
@Schema(description = "Schema for Developer object...")
public class Developer 

    @Schema(required = true, description = "First name of the developer")
    private String firstName;
    @Schema(required = true, description = "Last name of the developer")
    private String lastName;
    @Schema(required = true, implementation = Rank.class)
    private Rank developerRank;

截取生成的 OpenAPI 3.0 文档：

 schemas:
    Developer:
      description: Schema for Developer object...
      required:
      - developerRank
      - firstName
      - lastName
      properties:
        developerRank:
          description: |-
            <div class=\"renderedMarkdown\"><p>Rank of developer.</p>\n" +
                    "<p>Valid values are:</p>\n" +
                    "<ul>\n" +
                    "<li>'JUNIOR_DEVELOPER_1': Text for junior 1.\n" +
                    "<li>'JUNIOR_DEVELOPER_2': Text for junior 2.\n" +
                    "<li>'JUNIOR_DEVELOPER_3': Text for junior 3.\n" +
                    "<li>'SENIOR_DEVELOPER_1': Text for senior 1.\n" +
                    "<li>'SENIOR_DEVELOPER_2': Text for senior 2.\n" +
                    "<li>'SENIOR_DEVELOPER_3': Text for senior 3.\n" +
                    "</ul>\n" +
                    "<p>Random text...\n" +
                    "and has to be added to this API definition as well.</p></div>
          type: string
          properties:
            value:
              type: string
        firstName:
          description: First name of the developer
          type: string
        lastName:
          description: Last name of the developer
          type: string

但是，如果我在 Developer 类中的枚举之前删除 @Schema 注释，我会得到生成的枚举值，但没有描述和所需的值，如下所示：

schemas:
    Developer:
      description: Schema for Developer object...
      required:
      - firstName
      - lastName
      properties:
        developerRank:
          enum:
          - JUNIOR_DEVELOPER_1
          - JUNIOR_DEVELOPER_2
          - JUNIOR_DEVELOPER_3
          - SENIOR_DEVELOPER_1
          - SENIOR_DEVELOPER_2
          - SENIOR_DEVELOPER_3
          type: string
        firstName:
          description: First name of the developer
          type: string
        lastName:
          description: Last name of the developer
          type: string

有没有办法让我同时拥有枚举值和描述，或者我做错了什么？

【参考方案1】：

您可以使用枚举的@Schema 通过指定实现类来指示它使用 value 属性而不是 name 属性。

例如

@Schema(implementation = Rank::class)
public enum Rank 
    JUNIOR_DEVELOPER_1("junior_developer_1"),
    JUNIOR_DEVELOPER_2("junior_developer_2"),
    JUNIOR_DEVELOPER_3("junior_developer_3"),
    SENIOR_DEVELOPER_1("senior_developer_1"),
    SENIOR_DEVELOPER_2("senior_developer_2"),
    SENIOR_DEVELOPER_3("senior_developer_3");

    private String value;

    Rank(String value) 
        this.value = value;
    
    :

【讨论】：

如何使用value 属性而不是name 属性？我什至在编译器中尝试过（在修正了你的:: 错字之后，它没有按承诺工作。