Question

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

例如，JSON路径链接。[]。小部件。[]。contentType比用sprockets.[].widgets.[].contentType以等宽字体打印的可变宽度字体更难读取。

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

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

提前感谢您的帮助。

Answer 1

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

与此同时，您可以使用custom snippet templates执行所需操作。例如，要自定义请求字段路径的格式，您需要在request-fields.snippet中提供如下所示的src/test/resources/org/springframework/restdocs/templates文件：

|===
|Path|Type|Description

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

{{/fields}}
|===

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

Answer 2

您还可以使用asciidoctor格式代码，例如＆＃39; m＆＃39;对于等宽：

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：如何创建参数，路径和响应字段代码块

2 个答案: