Standard ISO 8601 format of ±HH:MM for ZoneOffset in swagger instead of JSON

Question

I'm currently working on Java application, which works with the orders. In some @RestController methods I return an instance of an Order class, which contains a timezone field.

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Order {
   private ZoneOffset timezone;
}

When I generate swagger with spring-boot tools it creates a json for responses, which looks like this

{
"timezone": {
    "totalSeconds": 0,
    "id": "string",
    "rules": {
      "fixedOffset": true,
      "transitions": [
        {
          "offsetBefore": {
            "totalSeconds": 0,
            "id": "string"
          },
          "offsetAfter": {
            "totalSeconds": 0,
            "id": "string"
          },
          "duration": {
            "seconds": 0,
            "nano": 0,
            "negative": true,
            "zero": true,
            "units": [
              {
                "dateBased": true,
                "timeBased": true,
                "durationEstimated": true
              }
            ]
          },
          "gap": true,
          "dateTimeBefore": "2023-02-27T18:33:30.403Z",
          "dateTimeAfter": "2023-02-27T18:33:30.403Z",
          "instant": "2023-02-27T18:33:30.403Z",
          "overlap": true
        }
      ],
      "transitionRules": [
        {
          "month": "JANUARY",
          "timeDefinition": "UTC",
          "standardOffset": {
            "totalSeconds": 0,
            "id": "string"
          },
          "offsetBefore": {
            "totalSeconds": 0,
            "id": "string"
          },
          "offsetAfter": {
            "totalSeconds": 0,
            "id": "string"
          },
          "dayOfWeek": "MONDAY",
          "dayOfMonthIndicator": 0,
          "localTime": {
            "hour": 0,
            "minute": 0,
            "second": 0,
            "nano": 0
          },
          "midnightEndOfDay": true
        }
      ]
    }
  }
}

which is not human-readable.

I want swagger to generate the default value, like +01:00 (like it returns in responses, when I send requests to my api).

I tried to use annotations like

@ApiModelProperty(example = "+01:00")

or

@ApiParam(defaultValue="+01:00")

, but nothing worked out for me.

I know that spring-boot tools can generate a human-readable json for ZonedDateTime (like this

"time": "2023-02-27T18:33:30.403Z"

). So I hope there is way to make the same thing for ZoneOffset.

P.S. I can not replace it is used in different calculations and convert it into string and back seems kind of problematic.

Answer 1

I found the solution in io.swagger.v3.oas.annotations.media.Schema

@Schema(example = "+01:00")
private ZoneOffset timezone;

generates the same result as I expected.