Spring restdocs 使用 asciidoc 有条件地高亮可选参数

Question

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

我的自定义请求-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 中的 'optional' 值被正确呈现（'true' 或 'false' 视情况而定），但 ifeval 未被解析（因此在最终 html，没有错误）。

我为表达式尝试了不同的语法，但 none 似乎有效；关于什么是正确语法的任何提示（如果有）？我正在考虑定义一个自定义属性并使用 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}}
|===

Spring restdocs 使用 asciidoc 有条件地高亮可选参数

Spring restdocs conditionally highlight optional parameters with asciidoc

java

maven

rest-assured

asciidoctor

spring-restdocs