How to add example in an API response without losing Schema

[ianwallen]

How to add example in an API response without losing the Schema?

This case is based on Java Map object for Json representation.

i.e. if I use the following
@ApiResponse(responseCode = "200", description = "OK")

I get the following correct response

"responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object"
                  }
                }
              }
            }
          }

But if I modify the @apiresponse to add an example using the following

@ApiResponse(responseCode = "200", description = "OK",
			content = @Content(examples = {@ExampleObject(value = "{\"Key\": \"Value\"}")})
	)

Then the response object is now incorrect.

"responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "Key": "Value"
                }
              }
            }
          }
        }

The Schema gets removed.

So - how would I add a example to the existing @apiresponse without losing the schema? Is this a bug?

I have created a unit test in the following branch for app51.
https://github.com/ianwallen/springdoc-openapi/tree/how_to_add_example_response_json

It produced the following error.

java.lang.AssertionError: paths./test5.post.responses.200.content.application/json
Expected: schema
     but none found

Thank you

[r4soft]

Hello,

I have the same issue when migrating from Springfox. It seems like in order to get the default schema on Springfox, the @content must either not be defined, or defined with all attributes without any defaults generated.
I was also hoping that useReturnSchema=true would be taken into account, but it has no effect as well.

If this is somehow an expected behavior due to OpeanAPI specs (or in general a breaking change), can you at least consider a config property which would allow this?

In project I'm part of, we try to minimise the amount of manual API doc definitions for internal APIs and this one seems like a good candidate for an intuitive default behavior - unless I'm missing the issue here, of course.

Regards

[bnasslahsen]

@ianwallen,

As long a you added the@Content annotation, it will be used for reference.
You need to complete it with your Schema response, for example:

@ApiResponse(responseCode = "200", description = "OK",
	content = @Content(schema = @Schema(type = "object", additionalPropertiesSchema = Object.class), examples = {@ExampleObject(value = "{\"Key\": \"Value\"}")})
)