Swagger2Markup : how to group by tags when using Swagger remote endpoint from test?

Question

I'm using the great swagger2markup plugin to generate Asciidoc documentation for my REST API as provided by Swagger. I have followed swagger2markup documentation and I am using a Spring MVC integration test to generate markup from my Springfox Swagger endpoint like this (I'm using Maven) :

@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = { AppConfig.class, SwaggerConfig.class })
public class DocumentationIT {

    protected MockMvc mockMvc;

    @Autowired
    protected WebApplicationContext webApplicationContext;

    @Rule
    public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("src/docs/asciidoc/apidoc/generated-snippets");

    @Before
    public void setUp(){
        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(this.restDocumentation))
                .build();
    }

    @Test
    public void convertSwaggerToAsciiDoc() throws Exception {
        this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(
                        Swagger2MarkupResultHandler
                                .outputDirectory("src/docs/asciidoc/apidoc")
                                .withExamples("src/docs/asciidoc/apidoc/generated-snippets").build())
                .andExpect(status().isOk());
    }
}

Everything is working great and all my paths are in my final documentation, however paths all appear directly at the root and are not grouped by resources (i.e. by controllers), so Method 1 from Controller 1 will appear at the same level as Method 2 from Controller 2.

My output :

What I'd like :

From what I can see, when using generation from a local file like in this swagger2-markup Maven project template you can specify a property to tell swagger2markup to group your paths by tags using the config property <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>, however there does not seem to be such configuration when using Swagger2MarkupResultHandler from a test. The only option is withMarkupLanguage() but there is no withPathsGroupedBy() method...

Am i missing something here ?

Answer 1

As you mentioned, there is a property of swagger2markup.pathsGroupedBy provided by swagger2Markup to specify how the paths should be grouped. However, Swagger2MarkupResultHandler do not provide API to support the configuration.

According to Swagger2Markup API,

The properties of Swagger2Markup are defined in the class io.github.swagger2markup.Swagger2MarkupProperties. The properties are considered in the following order:

1. Java System properties

2. Custom properties

3. Default properties (included in Swagger2Markup)

it is possible to configure it by using system properties. Therefore, you can set a system property of swagger2markup.pathsGroupedBy to TAGS in the test.

If you prefer to configure it with Java API, you may extend Swagger2MarkupResultHandler and override the handle method with the use of Swagger2MarkupConfigBuilder API.