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

Question

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

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

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

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

在此先感谢您的帮助。

G

Answer 1

我认为 REST Docs 应该默认执行此操作。我已经打开了一个将在 1.1 中修复的问题：https://github.com/spring-projects/spring-restdocs/issues/230。谢谢建议。

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

|===
|Path|Type|Description

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

{{/fields}}
|===

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

Answer 2

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

m|{{path}}

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

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

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

见http://asciidoctor.org/docs/user-manual/#cols-format

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

Spring-restdocs: how to make parameters, paths and response fields code blocks

java

documentation

spring-restdocs