java - Spring Restdocs 使用 asciidoc 有条件地突出显示可选参数

Question

我正在使用 spring Restdocs 在我的 REST webapi 上生成文档；我已经集成了这个东西，并且生成了我的html(maven + asciidoc 插件，放心的api)。 我遇到的唯一问题是 ifeval 要么不像宣传的那样工作，要么是我弄错了。

我的自定义 request-fields.snippet 如下所示:

|===
|Path|Type|Description|Optional

{{#fields}}
 |{{#tableCellContent}}
ifeval::["{optional}"=="true"]
   `{{path}}`
endif::[]
ifeval::["{optional}"="false"]
   *`{{path}}`*
endif::[]
  {{/tableCellContent}}
  |{{#tableCellContent}}`{{type}}`{{/tableCellContent}}
  |{{#tableCellContent}}{{description}}{{/tableCellContent}}
  |{{#tableCellContent}}{{optional}}{{/tableCellContent}}

{{/fields}}
|===

tablecellcontent 中的“可选”值已正确呈现(“true”或“false”取决于具体情况)，但 ifeval 未解析(因此在最终 html 上显示其自身未解析，没有错误)。

我尝试了不同的表达式语法，但似乎都不起作用；关于什么可能是正确的语法(如果有)的任何提示？ 我正在考虑定义一个自定义属性并使用 ifndef 来获得相同的结果，但如果可能的话，我更愿意使用现有的 optional() 支持。

根据要求，我添加生成的 .adoc

|===
|Path|Type|Description|Optional

|
ifeval::["{optional}"=="true"]
   `name`
endif::[]
ifeval::["{optional}"=="false"]
   *`name`*
endif::[]
|`String`
|Name of the new Axis
|false

|
ifeval::["{optional}"=="true"]
   `description`
endif::[]
ifeval::["{optional}"=="false"]
   *`description`*
endif::[]
|`String`
|Description of the new Axis
|true

|
ifeval::["{optional}"=="true"]
   `tags[]`
endif::[]
ifeval::["{optional}"=="false"]
   *`tags[]`*
endif::[]
|`TagDto[]`
|Hierarchical view of axis' tags
|false

|
ifeval::["{optional}"=="true"]
   `tags[].id`
endif::[]
ifeval::["{optional}"=="false"]
   *`tags[].id`*
endif::[]
|`Number`
|Id of the tag
|false

|
ifeval::["{optional}"=="true"]
   `tags[].name`
endif::[]
ifeval::["{optional}"=="false"]
   *`tags[].name`*
endif::[]
|`String`
|Name of the tag
|false

|
ifeval::["{optional}"=="true"]
   `tags[].children`
endif::[]
ifeval::["{optional}"=="false"]
   *`tags[].children`*
endif::[]
|`TagDto[]`
|Child tags for this tag, if any
|true

|===

Answer 1

问题出在您的自定义模板中，您在 ifeval 宏中使用 {optional} 而不是 {{optional}} 。这意味着 {可选} 不会被字段的 可选 属性替换，因此，Asciidoctor 正在评估 "{可选}"== “true” 或 “{可选}”==“false”。

您需要更新模板才能使用{{可选}}:

|===
|Path|Type|Description|Optional

{{#fields}}
 |{{#tableCellContent}}
ifeval::["{{optional}}"=="true"]
   `{{path}}`
endif::[]
ifeval::["{{optional}}"=="false"]
   *`{{path}}`*
endif::[]
  {{/tableCellContent}}
  |{{#tableCellContent}}`{{type}}`{{/tableCellContent}}
  |{{#tableCellContent}}{{description}}{{/tableCellContent}}
  |{{#tableCellContent}}{{optional}}{{/tableCellContent}}

{{/fields}}
|===