I don't know if this is the correct place to talk about this. I've started to use spring-auto-restd...

# spring

[Wesley Acheson]

I don't know if this is the correct place to talk about this. I've started to use spring-auto-restdoc (third party project).

It infers a property in the api is optional based on if its a nullable type. However I've got a few data classes that use default values, which are not marked as nullable. So from an API consumers point of view they are nullable.

Whats the best way to approach this? Mark the values (val as nullable ). This leads to unnecessary null checks later. Or somehow change how Jackosn creates its PropertyMetadata object.

---
I'm going to cross post to stack overflow.

[thanksforallthefish]

have you tried using @get:Nullable annotation on the nullable fields? either java or spring one?

[thanksforallthefish]

alternatively, autorestdocs uses javadoc to customize description and other details, but I have no idea if javadoc can describe a nullable field, ie something like

/**
* @param aField, @nullable <-- this does not exist, and I don't know if there is something equivalent
*/

[thanksforallthefish]

I am not a big fan of autorestdocs, it seems to defeat one of the point of restdocs that is forcing you to write meaningful documentation, as well as breaking tests when you unexpectedly change the api, for instance by removing a field (pretty sure autorestdocs won’t fail in this case)

[Wesley Acheson]

Yeah I hear you about the test failing. However I also feel that the actual documentation is a headache in the test case, when you have a highly nested object. I started converting a test case to Auto and then demoed to my team. In the end the conclusion we reached is that its easier to maintain the description in the kdoc, and that it forces the wider team to write kdoc/javadoc.

[thanksforallthefish]

for sure the main problem with restdocs is the introduction in an existing project. starting from scratch the pain of the documentation is not too bad