在 Spring Auto Rest Docs 中自定义章节标题

Question

我想在 Spring Auto Rest Docs 生成的 auto-section.adoc[] 文件中自定义部分 "title"。 Spring Auto Rest Docs 使用方法上的 @title Javadoc 标记（如果存在）或方法名称（如 docs 中所述）解析章节标题，但我不能包含 @title 在作为控制器的方法的 Javadoc 标记中 class 来自其他 JAR，我也不想要默认生成的方法名称。那么，如何在 Spring Auto Rest Docs 中自定义章节标题。

例如在自动生成的 auto-section.adoc[]

我不要

=== Resolved Method Name

我要

=== Something else

有什么帮助吗？谢谢。

Answer 1

Spring Auto REST Docs 通过查看 @title 标记来确定标题，如果找不到，则采用方法名称。目前没有办法直接自定义此行为。如果您无法修改 Javadoc，就像您的情况一样，您必须通过代码段添加信息。至少有两个选项：

创建自定义模板。但是这样一来，您只能使用该代码段可用的信息，因此 hard-coding 文本没有太多替代方案。参见 https://scacap.github.io/spring-auto-restdocs/#snippets-customization
创建自定义代码段。这使您可以完全控制所有内容，因此可以创建一个片段，将 "Something else" 作为输入并将其用作标题。请参阅 https://scacap.github.io/spring-auto-restdocs/#snippets-custom to create custom snippets and https://scacap.github.io/spring-auto-restdocs/#snippets-section-custom-snippet 在部分代码段中包含自定义代码段。

Answer 2

我在 auto-section.adoc 中实现了自定义部分标题，如下所示：

1) 我创建了扩展 SectionSnippet:

的自定义部分片段

class CustomSectionSnippet extends SectionSnippet {

    private final String title;

    public CustomSectionSnippet(final Collection<String> sectionNames, final boolean skipEmpty,
            final String title) {
        super(sectionNames, skipEmpty);
        this.title = title;
    }

    @Override
    protected Map<String, Object> createModel(final Operation operation) {
        final Map<String, Object> model = super.createModel(operation);

        if (title != null) {
            model.put("title", title);
        }

        return model;
    }

}

2) 然后是扩展 SectionBuilder:

的自定义部分构建器

class CustomSectionBuilder extends SectionBuilder {

    private Collection<String> snippetNames = DEFAULT_SNIPPETS;
    private final boolean skipEmpty = false;
    private String title;

    @Override
    public CustomSectionBuilder snippetNames(final String... snippetNames) {
        this.snippetNames = Arrays.asList(snippetNames);
        return this;
    }

    public CustomSectionBuilder sectionTitle(final String title) {
        this.title = title;
        return this;
    }

    @Override
    public SectionSnippet build() {
        return new CustomSectionSnippet(snippetNames, skipEmpty, title);
    }
}

3) 然后像这样使用它：

@Test
void testApi() throws Exception {

    final MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
    params.add("name", "test");

    this.mockMvc.perform(post("/api")
            .params(params)
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andDo(commonDocumentation(
                    new CustomSectionBuilder()
                        .sectionTitle("Something else") // <-- custom section title
                        .snippetNames(
                                AUTO_AUTHORIZATION, 
                                AUTO_REQUEST_FIELDS, 
                                REQUEST_HEADERS,
                                REQUEST_PARAMETERS, 
                                RESPONSE_FIELDS, 
                                CURL_REQUEST, 
                                HTTP_RESPONSE)
                        .build()
            ));

}

现在我可以将 Something else 作为章节标题传递，它将包含在自动生成的 auto-section.adoc 文件中。

感谢@florian-benz 的帮助:)

在 Spring Auto Rest Docs 中自定义章节标题

Customize Section title in Spring Auto Rest Docs

spring-auto-restdocs