Spring-restdocs:如何生成参数、路径和响应字段代码块

Question

我使用spring-restdocs生成API文档，我希望将所有参数、路径和响应字段JSON路径打印为表中的代码节(Asciidoc中的backticks)。

例如，JSON路径链轮.[].widgets.[].contentType在可变宽度字体中比以单空格打印的sprockets.[].widgets.[].contentType更难读取。

请求参数和路径参数也是如此--它们是应该以单空间打印的令牌。

用实现这一点的最简单方法是什么？

提前感谢您的帮助。

G

Answer 1

我认为REST文档在默认情况下应该这样做。我已经打开了一个将在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}}周围的背面。

Answer 2

您还可以使用asciidoctor格式代码，例如“m”用于单空间：

m|{{path}}

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

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

(我知道这不是你所要求的，但是对于任何一个刚接触过asciidoc的spring用户来说，知道有很多简单的定制选项可能会有所帮助。)

请参阅http://asciidoctor.org/docs/user-manual/#cols-format