Combine with MicroProfile OpenAPI: Example of date-time in Schema can not display this format "YYYY-MM-DDTHH:MM:SSZ", will report "OrderedMap" or this "YYYY-MM-DDTHH:MM:SS.MSZ" format

[yay9096]

Describe the bug
Original bug from here eclipse/microprofile-open-api#543
Based on open liberty and MicroProfile OpenAPI [2.0.1], We want to display example for date-time field as this format "YYYY-MM-DDTHH:MM:SSZ" in the web html, so we Sechema defined as bellow in Java code:
@Schema(name = "created_at", format = "date-time")
@Schema(name = "last_updated_at", format = "date-time", example = "2018-03-20T09:12:28Z")
@Schema(name = "started_at", format = "string", example = "2018-03-20T09:12:28Z")
Steps to Reproduce
After build code, and deploy local-host liberty, check http://localhost:9080/openapi/ui, Schema display OrderedMap error

And Example value will display as bellow: for the first item did not use example, it will display "YYYY-MM-DDTHH:MM:SS.MSSZ", and for others example, it will display {}

Expected behavior

Diagnostic information:

• OpenLiberty Version: 21.0.0.9
• Affected feature(s) [e.g. mpHealth-3.0]
• Java Version: JavaEE 8
• server.xml configuration (WITHOUT sensitive information like passwords)
• If it would be useful, upload the messages.log file found in $WLP_OUTPUT_DIR/messages.log

Additional context
Add any other context about the problem here.

[Azquelt]

Investigation

I reproduced the problem with a test data class which looks like this:

public class TestData {
    @Schema(name = "created_at", format = "date-time")
    public String createdAt;
    @Schema(name = "last_updated_at", format = "date-time", example = "2018-03-20T09:12:28Z")
    public String lastUpdated;
    @Schema(name = "started_at", format = "string", example = "2018-03-20T09:12:28Z")
    public String startedAt;
}

From what I can see, the produced OpenAPI document at /openapi looks correct for all versions of the mpOpenAPI feature. Examples from mpOpenAPI-1.1.
YAML:

  schemas:
    TestData:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        last_updated_at:
          type: string
          format: date-time
          example: 2018-03-20T09:12:28Z
        started_at:
          type: string
          format: string
          example: 2018-03-20T09:12:28Z

JSON:

    "schemas": {
      "TestData": {
        "type": "object",
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2018-03-20T09:12:28Z"
          },
          "started_at": {
            "type": "string",
            "format": "string",
            "example": "2018-03-20T09:12:28Z"
          }
        }
      }
    }

However, when rendered in swagger-ui, using mpOpenAPI-1.0 or -1.1, I do see the issue with the example object and schema described in the defect:

{
  "created_at": "2022-07-14T10:23:48.664Z",
  "last_updated_at": {},
  "started_at": {}
}

Diagnosis

When the OpenAPI UI is loaded, it first fetches the OpenAPI document from /openapi and parses it to find the operations and datatypes to display. It retrieves /openapi with the header Accept: application/json, */*.

mpOpenAPI-1.1 returns the document in YAML format with the header Content-Type: text/plain;charset=UTF-8
mpOpenAPI-2.0 returns the document in JSON format with the header Content-Type: application/json

Therefore I think two things have gone wrong:

1. mpOpenAPI-1.0 and -1.1 do not parse the Accept header properly. It looks like they just check for it being exactly equal to application/json.
2. The OpenAPI UI does not parse the YAML representation correctly.
   • The OpenAPI UI is based on Swagger UI which seems to use js-yaml to do its parsing
   • Needs some debugging to work out what's going wrong here. Mostly it looks like Swagger UI specifies SCHEMA_JSON when parsing YAML which shouldn't do anything clever with your timestamp strings, but the way it's appearing as an object suggests that it is being parsed as something different.

Conclusion

It's possible for you to work around the issue by updating to mpOpenAPI-2.0 or later which does not have this issue

I will work on improving the parsing of the Accept header in mpOpenAPI-1.0 and -1.1 since it's clearly broken. (It's not perfect in mpOpenAPI-2.0+ either but it at least copes with the request made by Swagger UI.)

I will look into raising a bug with Swagger UI on the way they parse timestamps in examples.

[yay9096]

@Azquelt Thank you for quick response, your means that microprofile-openapi-2.0 fix the issue? But we have tried microprofile-openapi-2.0.1 still does not work.

[Azquelt]

Yes, using the mpOpenAPI-2.0, -3.0 or -3.1 feature in your server.xml should fix the issue.