Fixing Swagger-Ui's JSON-example - Show JsonNumber instead of Object

Question

In our Java/Spring project we use Swagger-Ui for automatically documenting our REST-APIs.
Lately I went on to try to ensure proper documentation for all our APIs and found, that for some endpoints the JSON-Structure for the arguments of the methods are odd.

In the project, we have a Type "SerialNo" which is basically an Integer in a specific range (10000000 - 39999999).

Internally we use Jackson for Serializing and Deserializing our Objects (e.g. for the event broker) and we have set it up that in the JSON-Document the SerialNumber looks like an integer

// Product
{
  "header": { // type: ProductHeader
    "serialNo": 17654321
    ...
  }
  "wildly": {
    "nested": {
      "and": "grown"
      "structures": 12
    }
  }
}

and this is also the structure that is expected by the REST-Call.

Now the Swagger-Ui shows this as example:

// Product
{
  "header": {
    "serialNo": {} // <--- This is missleading
    ...
  }
  "wildly": {
    "nested": {
      "and": "grown"
      "structures": 12
    }
  }
}

I found that I could provide an example for the param that takes this structure by using @ApiParam(example = "..."), but since the structure has grown large, I don't feel like this is satisfiable, also the SerialNo will appear in multiple structures and I think it is teadious and errorprone to provide an example for every occurence in the API-doc.

I thried @ApiParam to the field in ProductHeader which is the object in "header":

@Getter
@Setter
public class ProductHeader {
   @JsonProperty
   @ApiParam(example = "17654321") private SerialNo serialNo;
   // ...
}

but this doesn't change a thing.

Is there a possibility to use swaggers documentation generation capatiblities to have the correct example output without providing an example for the full structure everytime?

Fixing Swagger-Ui's JSON-example - Show JsonNumber instead of Object

0 Answers0