Improve the combination of Spring REST docs and Auto REST docs for undocumented fields

[celcius112]

My team has recently added Spring Auto REST docs to our documentation, which uses normal Spring REST docs. We are pretty strict, so we fail the test if there is an undocumented field 😄. We also want to be this strict with Auto REST docs, by setting failOnUndocumentedParams to true by default.

However, problems arise when we combine an old Spring REST docs test with the newer Auto REST docs, as failOnUndocumentedParams does not take into account the snippets generated by Spring REST docs, and as such Auto REST docs fails because of undocumented fields.

I know it might be difficult to implement, because Auto REST docs does not necessarily have a hand on Spring REST docs' generated snippets. But maybe instead of failing eagerly if failOnUndocumentedParams is true we can let the classic Spring REST docs handle the failure for undocumented fields if we are generating the snippets using it ?

[jmisur]

Spring Auto REST Docs does undocumented validation only on it's own snippets. This means that if you configure this flag in Auto REST Docs and classic REST Docs, you need to satisfy both (Javadoc in former and fieldWithPath-style in the latter). We are not communicating or cooperating on any snippets and these worlds are strictly separated. You need to configure one or the other for snippets of the same type (request/response fields, query/path params) or satisfy both.

[celcius112]

Ok so if I understand correctly, given this project, the test SpringAutoRestDocsUndocumentedApplicationTests#classic_rest_docs will always fail unless I document the SpringAutoRestDocsUndocumentedApplication#RestDocs class ? Even though I want this object to be documented using classic REST docs ? (unless I'm missing something)

[jmisur]

Hi, see SARD+SRD example where you can use both snippets and combine in whatever way necessary. I think you need to skip the SARD snippet in that particular test from being generated, so that only SRD snippet will be used and manually documented by you. You can achieve that by having custom section builder. Let me know if it worked.

[celcius112]

Hello, thanks for your answer. Problems arise in your example when the mockMvc variable is initialize with responseFields().failOnUndocumentedFields(true). The test will fail with error Following response fields were not documented: [id, meta, meta.type,...] even though you are clearly documenting the response with classic REST docs. Maybe this is by design, but I think this is mostly counter-intuitive and even a big problem for legacy projects jumping into the REST Docs wagon 😢

[jmisur]

Hi, unfortunately, SARD and SRD are not cooperating automatically, so you either put responseFields().failOnUndocumentedFields(true) only on tests which require SARD documentation and leave it out for tests which do SRD documentation.