java - Spring-restdocs：如何制作参数、路径和响应字段代码块

Question

我正在使用 spring-restdocs 生成 API 文档，并且我希望将所有参数、路径和响应字段 JSON 路径打印为表格内的代码部分（Asciidoc 中的反引号）。

例如，JSON 路径 sprockets.[].widgets.[].contentType 比以等宽字体sprockets.[].widgets.[].contentType打印的可变宽度字体更难阅读。

请求参数和路径参数也是如此——这些是应该以等宽字体打印的标记。

使用 Spring-restdocs 实现这一目标的最简单方法是什么？

提前感谢您的帮助。

G

score 2 · Accepted Answer

我认为 REST Docs 默认应该这样做。我打开了一个将在 1.1 中修复的问题：https ://github.com/spring-projects/spring-restdocs/issues/230 。谢谢你的建议。

同时，您可以使用自定义代码段模板做您想做的事。例如，要自定义请求字段路径的格式，您需要在其中提供一个request-fields.snippet文件src/test/resources/org/springframework/restdocs/templates，如下所示：

|===
|Path|Type|Description

{{#fields}}
|`{{path}}`
|{{type}}
|{{description}}

{{/fields}}
|===

注意周围的反引号{{path}}。

score 0 · Accepted Answer

您还可以使用 asciidoctor 格式化代码，例如 'm' 表示等宽：

m|{{path}}

您甚至可以更改列宽和对齐方式，例如，相对宽度为 4-4-2 的三列和第三列居中对齐：

[cols="2*4,^2"]
|===
|Parameter|Description|Optional

（我知道这不是您所要求的，但对于任何刚接触 asciidoc 的 spring-restdocs 用户来说，知道有很多简单的自定义选项可能会有所帮助）

2 回答 2