API Docs

Как вы пишете доки к API приложения? Какие средства используете? Документация актуальна? Часто для документирования HTTP API используется swagger, простой и понятный инструмент, но сегодня мы поговорим о чем-то чуть более сложном, о чем-то чуть более продвинутом, а именно о Spring REST Docs. Довольно удивительно, что в разных кругах REST обозначает не сколько стиль архитектуры, сколько, в принципе, использование HTTP для построения API приложения. Spring Rest Docs (SRD) - это один из проектов Spring, который позволяет писать документацию к вашим REST сервисам и вот каким образом. Знакомы с TDD? Успели полюбить написание тестов? Здесь это пригодится. Документация в проекте SRD генерируется на основе написанных вами тестов. Как это выглядит?

Упрощенно, процесс следующий: пишем тест -> запускаем его -> генерируется сниппет в формате asciidoctor -> сниппет компилируется в html/pdf/другие форматы.

Тест для Spring Boot выглядит следующим образом. Вы конфигурируете объект MockMvc, например, так (JUnit 5)

SpringBootTest
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class SampleJUnit5ApplicationTests {
  @Autowired
  private WebApplicationContext context;
  private MockMvc mockMvc;

  @BeforeEach
  public void setUp(RestDocumentationExtension restDocumentation) {
    this.mockMvc = MockMvcBuilders
      .webAppContextSetup(context).apply(
        documentationConfiguration(
          restDocumentation))
      .build();
  }
  ...
}

Затем с его помощью пишите тест, например, так

Test
 public void sample() throws Exception {
    this.mockMvc.perform(get("/"))
      .andExpect(status().isOk())
      .andDo(document("sample"));
  }

В результате у вас генерируются сниппеты, которые складываются в определенную папку в проекте, а уже из сниппетов генерируется документация. Какие я здесь вижу плюсы:

• документация всегда актуальна и есть пример запуска в виде теста;
• покрытие тестов неизменно растёт;

Минусы:

• навязывание TDD;
• документирование смешивается с тестированием (хотя, может быть это не минус).

Ниже дал ссылки, где можно почитать подробнее, если вы заинтересовались.

• Spring Rest Docs
• Getting Started
• Примеры на Github'e