Swagger2Markup：在测试中使用 Swagger 远程端点时如何按标签分组？

Question

我正在使用很棒的 swagger2markup plugin to generate Asciidoc documentation for my REST API as provided by Swagger. I have followed swagger2markup documentation 并且我正在使用 Spring MVC 集成测试从我的 Springfox Swagger 端点生成标记，就像这样（我正在使用 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());
    }
}

一切都很好，我的所有路径都在我的最终文档中，但是 路径都直接出现在根目录中，并且没有按资源分组（即按控制器），所以Controller 1 中的 Method 1 将与 Controller 2 中的 Method 2 出现在同一级别。

我的输出：

我想要什么：

据我所知，当使用像这样的本地文件生成时 swagger2-markup Maven project template 你可以指定一个属性来告诉 swagger2markup 使用配置 [=42] 按标签对你的路径进行分组=] <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>，但是在测试中使用 Swagger2MarkupResultHandler 时似乎没有这样的配置。唯一的选择是 withMarkupLanguage() 但没有 withPathsGroupedBy() 方法...

我是不是遗漏了什么？

Answer 1

如您所述，swagger2Markup 提供了属性 of swagger2markup.pathsGroupedBy 来指定路径的分组方式。但是，Swagger2MarkupResultHandler不提供API支持配置。

根据Swagger2Markup API，

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

Java System properties

Custom properties

Default properties (included in Swagger2Markup)

可以使用系统属性对其进行配置。所以可以在测试中设置一个系统swagger2markup.pathsGroupedBy的属性到TAGS

如果你更喜欢用 Java API 配置它，你可以扩展 Swagger2MarkupResultHandler and override the handle method with the use of Swagger2MarkupConfigBuilder API.

Swagger2Markup：在测试中使用 Swagger 远程端点时如何按标签分组？

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

maven

spring-mvc

swagger

springfox

spring-restdocs