spring-auto-restdocs

Customize Section title in Spring Auto Rest Docs


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.


Solution

  • 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 :)