Spring Auto Rest Docs 中的 Auto Section 标题级别

如何解决Spring Auto Rest Docs 中的 Auto Section 标题级别

这是我关于 StackOverflow 的第一个问题。

我使用的是 Java 11、Spring Boot 2.4.0、JUnit 5、Auto Rest Docs 2.0.9。

我在生成文档时收到以下警告：

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

第 2 行如下所示：==== Register

文档结构如下：

= 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[]

直接包含在 Level 1 section 中的所有代码段都有警告。

对于 Level 2 section 中的片段，一切正常。

我明白为什么会出现警告，但如何在自动生成的代码段中配置标题级别？

如果有一种方法可以将其配置为使部分标题为 2 级，则它可能会针对 Level 2 section 中的片段（如 expected level 3,got level 2）显示警告。

有没有办法自动配置自动生成的代码段内的部分标题级别？（基于包含的父节级别）

或者甚至是在每个单元测试中指定预期级别的方法。

我检查了文档，但没有找到任何东西。任何帮助表示赞赏。谢谢！

解决方法

可以通过 Snippet customization 配置标题级别，即通过提供具有不同级别标题的自定义片段模板。但是，这将适用于所有地方。或者，可以创建一个可以配置为使用不同模板的 Custom snippet。主要问题是代码片段看不到周围的 AsciiDoc，因此永远不知道它处于哪个级别。

这是当前的 Auto Section Snippet，标题为三级。

我们尝试将所有片段放在同一级别。然而，这并不总是奏效或始终如一地应用。因此，在实践中，我们会忽略这些警告。