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

Question

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

我的自定义请求字段.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 中的 'optional' 值被正确呈现('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}} .这意味着 {optional} 没有被该字段的 optional 属性替换，因此，Asciidoctor 正在评估 "{optional}"== "true" 或 "{optional}"=="false"。

您需要更新您的模板以使用{{optional}}:

|===
|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}}
|===