Customize Section title in Spring Auto Rest Docs

Question

I want to customize Section "title" in auto-section.adoc[] file generated by Spring Auto Rest Docs. Spring Auto Rest Docs resolves section title using @title Javadoc tag on the method(if present) or from the method name (as mentioned in docs), but i can't inlcude @title in the Javadoc tag of method as the controller class is from other JAR, also I don't want the default generated method name. So, how to customize Section title in Spring Auto Rest Docs.

E.g. In auto generated auto-section.adoc[]

I don't want

=== Resolved Method Name

I want

=== Something else

Any help? Thanks.

Answer 1

I achieved customizing section title in auto-section.adoc as below:

1) I created custom section snippet that extends 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) And then the custom section builder that extends 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) And then used it like this:

@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()
            ));

}

And now I'm able to pass Something else as a section title that will be included in the auto generated auto-section.adoc file.

Thanks @florian-benz for help :)

Answer 2

Spring Auto REST Docs determines the title by looking at the @title tag and if this is not found, the method name is taken. There is currently no way to directly customize this behavior. If you can not modify the Javadoc, like in your case, you have to add the information via the snippet. There are at least two options:

1. Create a custom template. But then you are limited to the information available to the snippet and thus there are not a lot of alternatives to hard-coding text. See https://scacap.github.io/spring-auto-restdocs/#snippets-customization
2. Create a custom snippet. This gives you full control over everything and thus a snippet could be created that takes "Something else" as an input and uses it as the title. See 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 to include custom snippets in the section snippet.