问题描述
这是我关于 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,标题为三级。
我们尝试将所有片段放在同一级别。然而,这并不总是奏效或始终如一地应用。因此,在实践中,我们会忽略这些警告。