Example value cannot be specified without having to specify a schema

[cnusp]

As far as possible I let springdoc-openapi autogenerate my OpenAPI specification, that is without my intervention. But examples need to be provided manually, because the autogenerated examples do not contain sensible values:

@RequestBody(
        content = @Content(
                examples = @ExampleObject(
                        value = "{ \"a\": \"sensible value\" }"
                )
        )
)
public void postMyRequestBody(@RequestBody MyRequestBody myRequestBody) {
    throw new NotImplementedException();
}

That compiles, but gives me a runtime error. Even though the type of the request body, defined as @RequestBody in the controller method, is actually known (and even used for the autogenerated example if I do not specify my own).

I need to add schema = @Schema(implementation = MyRequestBody.class) (which is redundant and unchecked, thus can lead to a discrepancy between springdoc-openapi annotation and the actual controller method). And even if I explicitly specify the schema, the example JSON is not validated (not parsed?) using that schema.

@RequestBody(
        content = @Content(
                schema = @Schema(implementation = MyRequestBody.class),
                examples = @ExampleObject(
                        value = "{ \"a\": 1 }"
                )
        )
)
public void postMyRequestBody(@RequestBody MyRequestBody myRequestBody) {
    throw new NotImplementedException();
}

Definition of done:

• automatically use MyRequestBody as the schema class
• validate the example (using that schema class)

[cnusp]

Validate the example does not work, thus definition of done not fulfilled. Please re-open.

[bnasslahsen]

Hi,

There is no strict requirement in the OpenAPI-Specification to validate the example compatibility with a schema.
We do not choose to integrate this validation on springdoc-openapi.
If the swagger-api integrates it, we will then reuse it.

[cnusp]

Hi,

I think that feature is not related to the specification, but is perfectly obvious because an invalid example is useless.

If I manually write the OpenAPI specification, then it is difficult to validate my examples. But if the specification is auto-generated, the developer expects the generator to check what it produces.

It does not necessarily have something to do with whether Swagger integrates that validation or not.