Використання механізму генерації OpenAPI документації

Підключення механізму генерації в існуючий проект

Використання механізму базується на підключенні maven plugin з послідуючим підключенням необхідних tiles з com.epam.digital.data.platform:low-code-platform-maven-tiles артефакту.

Підключення tiles plugin в pom.xml

Пропонується використовувати окремий maven profile для підключення tiles-maven-plugin. Це забезпечить ізоляцію генерації asciidoc Rest API від основного build lifecycle. 
  <profiles>
    <profile>
      <id>generate-rest-api-docs</id>
      <activation>
        <activeByDefault>false</activeByDefault>
      </activation>
      <build>
        <plugins>
          <plugin>
            <groupId>io.repaint.maven</groupId>
            <artifactId>tiles-maven-plugin</artifactId>
            <version>2.32</version>
            <extensions>true</extensions>
            <configuration>
              <buildSmells>pluginmanagement</buildSmells>
              <filtering>true</filtering>
              <tiles>
                <tile>com.epam.digital.data.platform:openapi-generator-tile:${ddm-maven-tails.version}</tile>
                <tile>com.epam.digital.data.platform:rest-api-adoc-generator-tile:${ddm-maven-tails.version}</tile>
                <tile>com.epam.digital.data.platform:rest-api-adoc-generator-clean-tile:${ddm-maven-tails.version}</tile>
              </tiles>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>

Конфігураційні параметри

Конфігураційний параметр Required Опис

apiDocsUrl

true

HTTP адреса сервісу для отримання rest api specification під час генерації swagger.json

ddm-maven-tails.version

true

Версія tiles артефактів. Параметр обов’язковий тільки для конфігурації tiles-maven-plugin.

swaggerPath

true

Шлях до swagger файлу для механізму swagger генерації та механізму генерації asciidoc rest api документації

Приклад задання параметрів в pom.xml:

<properties>
    <apiDocsUrl>http://localhost:7070/v3/api-docs</apiDocsUrl>
    <ddm-maven-tails.version>0.0.1-SNAPSHOT</ddm-maven-tails.version>
</properties>

Доступні tiles для використання

Назва Опис

openapi-generator-tile

Генерація swagger.json по запущеному spring boot application

rest-api-adoc-generator-clean-tile

Видалення раніше сгенерованої RestAPI adoc документації

rest-api-adoc-generator-tile

Генерація adoc RestAPI документація використовуючи swagger.json open api definition

Необхідний набір tiles повинен бути вказаний в конфігурації tiles-maven-plugin в pom.xml.

Розширення згенерованої документації

Розширення документації відбувається шляхом створення adoc файлів з певним шляхом, який і визначає місце в згенерованому документі для розширення. Всі розширення знаходяться в docs/modules/<module name>/pages/rest-api/rest-api-includes.

Використання intro.adoc

Для поверхневого опису RestAPI може використовуватись docs/modules/<module name>/pages/rest-api/rest-api-includes/intro.adoc файл.

Приклад:

file-structure-intro-example
Специфічний endpoint метод Rest API

Існує можливість розширення опису окремо кожного з rest api методів для ендпоінтів шляхом створення adoc файлів зі специфічним шляхом до файлу. Для цього необхідно створити adoc документ в docs/modules/<module name>/pages/rest-api/rest-api-includes/

Приклад:

file-structure-method-example
Використання snippets з прикладами викликів RestAPI

Приклади викликів необхідно зберігати в target/generated-snippets перед запуском rest-api-adoc-generator-tile. Для з’єднання прикладу виклику з адресою виклику використовується шлях до прикладу на файловій системі всередині generated-snippets директорії. Наприклад якщо приклад до POST методу version/candidates то шлях до прикладу з запитом повинен бути target/generated-snippets/versions/candidates/POST/http-request.adoc, а з відповіддю відповідно target/generated-snippets/versions/candidates/POST/http-response.adoc

Приклад:

file-structure-snippets-example
Генерування snippets з прикладами викликів RestAPI endpoints

Існує можливість отримати приклади викликів rest api (snippets) автоматично під час виконання unit тестів, котрі використовують org.springframework.test.web.servlet.MockMvc. Для цього необхідно підключити бібліотеку:

<dependency>
  <groupId>org.springframework.restdocs</groupId>
  <artifactId>spring-restdocs-mockmvc</artifactId>
  <version>${spring.restdocs.mockmvc.version}</version>
  <scope>test</scope>
</dependency>

В unit тестах в MockMvc додати MockMvcRestDocumentationConfigurer:

  @BeforeEach
  public void setUp(WebApplicationContext webApplicationContext,
      RestDocumentationContextProvider restDocumentation) {

    this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
        .apply(documentationConfiguration(restDocumentation))
        .build();
  }

При визові MockMVC.perform вказати за яким саме шляхом на файловій системі зберегти запити та відповіді.

  @Test
  @SneakyThrows
  void getVersionListTest() {
    ...
    mockMvc.perform(
            get(BASE_URL))
        .andExpectAll(
            ...
        )
        .andDo(document("versions/candidates/GET"));
    Mockito.verify(versionManagementService).getVersionsList();
  }

Після запуску тестів snippets будуть збережені в target/generated-snippets директорію, та можуть бути використані автоматично rest-api-adoc-generator-tile під час генерації основного asciidoc RestAPI документу.

Оскільки генерація asciidoc Rest API відбувається на фазі post-integration-test, то використання maven profile generate-rest-api-docs з прикладу вище не потребує додаткових налаштувань для запуску тестів та отримання snippets.
Повна структура файлів (приклад)
file-structure-full-example