How to annotate an inline response?

[rockxwre]

With springdoc-openapi my application generates OAS3 yaml specification based on the Swagger 3 annotations in the controllers and models.

What I want to achieve is to have an inline operation response. Something like this:

paths:
  /myoperation:
    get:
      ...
      responses:
        '200':
          content:
            application/json:
              schema:
                required:
                  - count
                  - results
                type: object
                properties:
                  count:
                    type: integer
                  results:
                    type: array
            ...

The annotations of the operation method in the controller class looks like this:

@ApiResponse(responseCode = "200",
             description = "OK",
             content = @Content(mediaType = "application/json", schema = @Schema(implementation = MyResponseDTO.class, requiredProperties = { "count", "results"} ))

and MyResponseDTO:

public class MyResponseDTO {

    @Schema(required = true, description = "")
    private long count;

    @ArraySchema(schema = @Schema(implementation = MyModel.class))
    private List<DTO> results;

    ... getters/setters

}

This results in a schema with:

...
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyResponseDTO'

...
components:
    MyResponseDTO:
      required:
      - count
      type: object
      properties:
        count:
          type: integer
          format: int64
        results:
          type: array
          items:
            $ref: '#/components/schemas/MyModel'

The response content is a reference instead of an inline object. Is there a way I can annotate the response/schema so that it will appear inline in the documentation?

I already posted this question as an issue for the springdoc-openapi. They however advised me to ask the question here.

So maybe someone here can help me out? Thanks!

Ramon Rockx

[webron]

I don't believe we have a way to do that (but @frantuma may correct me).

Why are you looking for an inline definition though? Generally speaking, referenced definitions are easier to manage, however, I'm curious to understand the use case.

[rockxwre]

A third party specified an OAS3 interface which our product has to implement. The interface documentation (yaml) contains inline operation responses. One of the requirements is to provide the same documentation. So, in other words, I am trying to annotate my Spring controllers/models to create documentation exactly like the one the third party provided. So it is not my personal choice to use inline responses, it is prescribed.

[webron]

Got it. So right now there's no simple way of doing this. You can manually describe the schema inside the @Schema annotation, but that would get painful if it's a big/complex class.

To make it more automated, you can create another annotation that says it should be inline, and extend the Reader to process it that way.

[rockxwre]

Okay, thank you for your suggestions. I will try the manual description. Maybe for the future an extra inline=true|false element for the @Schema annotation would be nice.