joffrey-bion / livedoc

A not-so-annotation-based documentation generator for REST and websocket services
MIT License
4 stars 2 forks source link

JSON output is affected by the user's custom ObjectMapper #106

Closed joffrey-bion closed 6 years ago

joffrey-bion commented 6 years ago

Describe the bug Multiple client side exceptions are due to the /jsondoc output not matching the format expected by Livedoc UI. For instance, when configuring a custom ObjectMapper to not serialize empty collections, using serializationInclusion="NON_EMPTY", the /jsondoc output will be malformed from the point of view of Livedoc UI. Undefined lists cause crashes in components like the flows list, or the format list of a type's property (see https://github.com/joffrey-bion/livedoc/issues/103 and https://github.com/joffrey-bion/livedoc/issues/104).

Expected behavior Livedoc UI should not break in this case. Either the JSON doc output should not be affected by the user's custom mapper, or the UI should deal with whatever peculiarity a user could introduce in his own mapper.

Environment/Context

joffrey-bion commented 6 years ago

As few options can be considered to fix this:

  1. sanitize the UI code with undefined checks
  2. locally force a serialization inclusion ALWAYS for the Livedoc object, in order to be sure all properties will be there even if the user's ObjectMapper is configured not to write some properties.
  3. create a specific mapper for Livedoc, and force it on the /jsondoc endpoint. I don't know if this is possible, and it might not work for everyone depending on how much they customize Livedoc

I don't like option 1 & 2 much, because it means we don't control our data anymore. The users could potentially do anything with the output. We don't just want to deal with this specific NON_EMPTY properties problem, we want to ensure the Livedoc's JSON stays consistent regardless of the user configuration.

Option 3 seems the way to go, but I'm not sure we can configure a mapper on a per-endpoint basis. I'll investigate.