Incompatibility with Swagger annotations

So I’m trying to generate the swagger API from code with swagger annotations. It all works well except Problem.statusType field.

Description

I am describing my endpoint’s responses like this:

@Operation(
    description = "Retrieve entity by id",
    responses = {
        @ApiResponse(
            responseCode = "404",
            description = "Entity not found",
            content = @Content(
                schema = @Schema(implementation = Problem.class),
                mediaType = APPLICATION_PROBLEM_JSON_VALUE))})

But because Problem.statusType field is not an integer as per API specification, but a class – the generated swagger output is wrong.

Expected Behavior

The following component are generated for swagger yaml:

Problem:
  type: object
  properties:
    instance:
      type: string
      format: uri
    type:
      type: string
      format: uri
    parameters:
      type: object
      additionalProperties:
        type: object
    title:
      type: string
    status:
      type: integer # <------- this
    detail:
      type: string

Actual Behavior

The following components are generated for swagger yaml:

Problem:
  type: object
  properties:
    ...
    status:
      $ref: '#/components/schemas/StatusType'
StatusType:
  type: object
  properties:
    statusCode:
      type: integer
      format: int32
    reasonPhrase:
      type: string

Possible Fix

Do you think this can be fixed at the library level? Or should I create a bug in problem spring web adapter better?

[bushwakko]

This is because the implementation used by the problem-detail library, has StatusType in the POJO, and registers a Jackson-Module to the ObjectMapper, that provides code to serialize the StatusType class to ensure the serialized output is an integer. The code that builds the model in Swagger (ModelResolver), however, tries to makes its own interpretation of the Problem class. Since the Module contains serialization code, and not any declarative config/metadata, it doesn’t take into account how that object is serialized by Jackson’s ObjectMapper.

I’m not sure what the solution is though, other than it needs to take into account all the information Jackson has.

It would have to analyze the Jackson-configuration, find which classes are serialized differently, and account for that in the model. Alternatively, the ModelResolver could instead populate and serialize a dummy object, analyze the resulting json and try to make a model based on that, or at least see where the json differs from its current model.

Edit: The ModelResolver method “resolve()” that does the interpretation, is 750 (!) lines long, and thus very hard to understand.

[bushwakko]

The biggest technical issue here is that without a declarative description of the serialization rules in the POJO or in the Jackson-Module/ObjectMapper, it’s very hard to deduce what the actual output is. It could be possible to pick up the serialization functions, but the output is either Object or String, so you won’t know what type it actually is.

A hacky way to figure it out, could be to populate each field in the POJO with a value describing the type of the field, then serializing the object and then mapping back from the string-values on each json property to a type, for use in the model.