Swagger2Markup: как сгруппировать по тегам при использовании удаленной конечной точки Swagger из теста?

Я использую отличный плагин swagger2markup для создания документации Asciidoc для моего REST API, предоставленной Swagger. Я следил за документацией swagger2markup и использую интеграционный тест 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());
    }
}

Все работает отлично, и все мои пути есть в моей окончательной документации, однако все пути отображаются непосредственно в корне и не группируются по ресурсам (т. е. по контроллерам), поэтому Method 1 из Controller 1 будут отображаться одновременно уровень как Method 2 от Controller 2.

Мой вывод:

введите здесь описание изображения

Что я хотел бы:

введите здесь описание изображения

Из того, что я вижу, при использовании генерации из локального файла, как в этом swagger2-markup Maven шаблон проекта, вы можете указать свойство, чтобы указать swagger2markup сгруппировать ваши пути по тегам, используя свойство конфигурации <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>, однако при использовании Swagger2MarkupResultHandler из теста такой конфигурации не существует. Единственный вариант - withMarkupLanguage(), а withPathsGroupedBy() метода нет...

Я что-то пропустил здесь?


person Pom12    schedule 26.09.2016    source источник


Ответы (1)


Как вы упомянули, существует свойство swagger2markup.pathsGroupedBy, предоставляемое swagger2Markup, чтобы указать, как следует группировать пути. Однако Swagger2MarkupResultHandler не предоставляет API для поддержки конфигурации.

Согласно Swagger2Markup API,

Свойства Swagger2Markup определены в классе io.github.swagger2markup.Swagger2MarkupProperties. Свойства рассматриваются в следующем порядке:

  1. Свойства системы Java

  2. Пользовательские свойства

  3. Свойства по умолчанию (включены в Swagger2Markup)

его можно настроить с помощью системных свойств. Таким образом, вы можете установить системное свойство swagger2markup.pathsGroupedBy в TAGS в тесте.

Если вы предпочитаете настраивать его с помощью Java API, вы можете расширить Swagger2MarkupResultHandler и переопределить метод handle с помощью Swagger2MarkupConfigBuilder API.

person Wilson    schedule 26.09.2016
comment
Спасибо за Ваш ответ. К сожалению, плагин springfox-staticdocs в настоящее время не зависит от версии Swagger2Markup, которая поддерживает системные свойства (в настоящее время он зависит от v0.9.2, где документ, который вы цитируете, кажется применимым к v1.0.0+). Однако ваше второе решение отлично работает, и даже если бы я предпочел иметь его непосредственно в библиотеке (я отправил pull request для этого), но на данный момент это достаточно хороший обходной путь, спасибо! - person Pom12; 27.09.2016