java - 为java对象设置OpenApi示例

Question

我有一个 java 类，我想对其进行注释，以获得记录良好的 API。该类如下:

package test;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "The Employee.", title = "Employee", type = "object")
public class Employee {

  @Schema(description = "Firstname.", example = "Alex", type = "string")
  private String firstname;

  @Schema(description = "The person.", type = "object")
  private Person person;

  public String getFirstname() {
      return firstname;
  }

  public Employee setFirstname(String firstname) {
      this.firstname = firstname;
      return this;
  }

  public Person getPerson() {
      return person;
  }

  public Employee setPerson(Person person) {
      this.person = person;
      return this;
  }
}

我在这里遇到的问题是，我似乎找不到一种方法来为属性 Person 设置示例。我尝试输入 json 字符串，但没有成功。是否有可能为对象树立榜样？谢谢。

这是我尝试过的:

...

  @Schema(description = "The person.", type = "object", example: "{'age': 30}")
  private Person person;

...

这会生成:

...

"example": "{'age': 30}"

...

但我正在寻找的是:

"example": {"age": 30}

Answer 1

要为 Employee 类中的 Person 对象设置 OpenAPI 示例，您可以使用 @Schema 注解。

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "The Employee.", title = "Employee", type = "object")
public class Employee {

  @Schema(description = "Firstname.", example = "Alex", type = "string")
  private String firstname;

  @Schema(description = "The person.", type = "object", example = "{ \"name\": \"John\", \"age\": 30 }")
  private Person person;

  public String getFirstname() {
      return firstname;
  }

  public Employee setFirstname(String firstname) {
      this.firstname = firstname;
      return this;
  }

  public Person getPerson() {
      return person;
  }

  public Employee setPerson(Person person) {
      this.person = person;
      return this;
  }
}