Настройте заголовок раздела в Spring Auto Rest Docs

Question

Я хочу изменить заголовок раздела в auto-section.adoc[]файл, созданный Spring Auto Rest Docs. Spring Auto Rest Docs разрешает заголовок раздела, используя@titleТег Javadoc в методе (если есть) или из имени метода (как указано в документации), но я не могу включить@titleв теге Javadoc метода, поскольку класс контроллера взят из другого JAR, также мне не нужно сгенерированное по умолчанию имя метода. Итак, как настроить заголовок раздела в Spring Auto Rest Docs.

Например, в автоматически созданном auto-section.adoc[]

Я не хочу

=== Resolved Method Name

я хочу

=== Something else

Любая помощь? Спасибо.

Answer 1

Я добился настройки заголовка раздела в 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 за помощь:)

Answer 2

Spring Auto REST Docs определяет заголовок, глядя на @titleтег, и если он не найден, берется имя метода. В настоящее время нет возможности напрямую настроить это поведение. Если вы не можете изменить Javadoc, как в вашем случае, вам необходимо добавить информацию через фрагмент. Есть как минимум два варианта:

1. Создайте собственный шаблон. Но тогда вы ограничены информацией, доступной для фрагмента, и поэтому не так много альтернатив жесткому кодированию текста. См. https://scacap.github.io/spring-auto-restdocs/
2. Создайте собственный сниппет. Это дает вам полный контроль над всем, и, таким образом, можно создать фрагмент, который принимает "Что-то еще" в качестве входных данных и использует его в качестве заголовка. См. https://scacap.github.io/spring-auto-restdocs/ для создания пользовательских сниппетов и https://scacap.github.io/spring-auto-restdocs/ чтобы включить пользовательские фрагменты в фрагмент раздела.