Set OpenApi examples for java objects

Question

I have a java class that I want to anotate in order to get a well documented API. The class is the following :

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

The problem I have here is that I can't seem to find a way to set an example when for the property Person. I tried putting a json string but that didn't work. Is it even possible to set an example for objects? Thanks.

Here's what I tried :

...

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

...

this generates :

...

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

...

but what I'm looking for is :

"example": {"age": 30}

Answer 1

To set OpenAPI examples for the Person object within the Employee class, you can use the @Schema annotation.

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