Auto Section title level in Spring Auto Rest Docs

Question

This is my first question on StackOverflow.

I am using Java 11, Spring Boot 2.4.0, JUnit 5, Auto Rest Docs 2.0.9.

I am getting the following warning when I am generating the document:

asciidoctor: WARNING: C:/{path-to-project}/build/generated-snippets/register_success/auto-section.adoc: line 2: section title out of sequence: expected level 2, got level 3

Line 2 looks like this: ==== Register

The structure of the document looks like this:

= API Methods
== Account Registration Operations
include::{snippets}/register_success/auto-section.adoc[]

== Other level 1 section
=== Level 2 section
include::{snippets}/{other-method-name}/auto-section.adoc[]

There are warnings for all snippets that are directly included inside a Level 1 section.

For the snippets inside the Level 2 section everything is fine.

I understand why the warning is present, but how can I configure the title level inside the auto generated snippet?

If there is a way to configure it so that the section title is of level 2, it will probably show a warning for the snippets inside the Level 2 section (like expected level 3, got level 2).

Is there a way that the level of the section title inside the auto generated snippet, is configured automatically? (based on the parent section level that is included in)

Or even a way to specify inside each Unit Test, the level that is intended to be.

I have checked the documentation but I did not found anything. Any help is appreciated. Thank you!

Answer 1

One can configure the title level via Snippet customization, i.e. by providing a custom snippet template with the title on a different level. However, this would apply to all places. Alternatively, one could create a Custom snippet that can be configured to use different templates. The main issue is that the snippet does not see the surrounding AsciiDoc and thus never knows on which level it is.

Here is the current Auto Section Snippet with the title on level three.

We try to put all snippets on the same level. However, this does not always work out or is applied consistently. So in practice, we ignore those warnings.