Kapitel 24 · Testing

Spring REST Docs: testgetriebene API-Dokumentation

Typ: LibraryVersion 2 ausführlich

Spring REST Docs kombiniert handgeschriebene AsciiDoc-Dokumentation mit Snippets, die aus Tests erzeugt werden.

Fachliche Einordnung

Dokumentation bleibt nur aktuell, wenn sie mit Tests gekoppelt ist. REST Docs zwingt Beispiele, Felder und Response-Verträge näher an den Build.

Enterprise-Merksatz: Spring REST Docs kombiniert handgeschriebene AsciiDoc-Dokumentation mit Snippets, die aus Tests erzeugt werden.

Technische Darstellung

Kernkonzepte

MockMvc oder REST Assured erzeugt Snippets.
AsciiDoc bindet Snippets ein.
requestFields und responseFields dokumentieren Verträge.
Dokumentation wird Teil des Build-Artefakts.
Gut kombinierbar mit Contract- und Integrationstests.

Wann einsetzen?

Du willst API-Dokumentation aus geprüften Beispielen erzeugen.
Du willst weniger Drift zwischen Doku und Implementierung.
Du brauchst menschenlesbare technische Dokumente.

Typische Fehler und Risiken

Nur Happy-Path dokumentieren.
Snippets ohne fachliche Erklärung.
Dokumentation nicht im CI-Build prüfen.

Legacy- und Modernisierungssicht

SOAP-WSDLs hatten formale Verträge; REST Docs kann bei REST-Migrationen überprüfbare, lesbare Ersatzdokumentation liefern.

Ausführliches Beispiel

Das Beispiel zeigt bewusst nicht nur Annotationen, sondern auch die Verantwortung der Schicht. In echten Projekten sollte der technische Spring-Code an Adapter- oder Konfigurationsrändern bleiben, während die Fachlogik testbar und möglichst frameworkarm bleibt.

@WebMvcTest(OrderController.class)
@AutoConfigureRestDocs
class OrderApiDocumentationTest {
    @Autowired MockMvc mvc;

    @Test
    void documentsPlaceOrder() throws Exception {
        mvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{"customerNumber":"C-100","sku":"SKU-1"}"))
            .andExpect(status().isCreated())
            .andDo(document("orders-place",
                requestFields(
                    fieldWithPath("customerNumber").description("Kundennummer"),
                    fieldWithPath("sku").description("Artikelnummer")),
                responseFields(fieldWithPath("id").description("Neue Order-ID"))));
    }
}

Checkliste für Reviews

Ist die Verantwortung des Bausteins klar: Framework steuert Lebenszyklus, Library wird gezielt benutzt?
Ist die Fachlogik außerhalb von Controller, Listener, Repository-Implementierung oder Konfiguration?
Sind Fehlerfälle, Timeouts, Security, Monitoring und Tests sichtbar modelliert?
Gibt es klare Grenzen zwischen DTO, Domäne, Persistence und Infrastruktur?