Thoughts on agile software development
Anyone who has ever worked with Web APIs, and who hasn’t, will be aware of the difficulties of testing in an API environment. When testing an API, there are two sides to consider, that of the producer and that of the consumer. If both do not work hand in hand, then problems are inevitable. Consumer contract tests are designed to avoid some of the difficulties in API testing.
Fasst drei Jahre nach dem ersten Beitrag zum eigenen API MarktDown ergibt sich ein zweiter Beitrag zum Thema. Bei der Durchsicht der eigenen Projekte fiel auf, dass in dem Projekt rest-markdown-plugin noch immer FreeMarker als Template-Engine verwendet wurde. Die erste Ad-Hoc Umstellung der Template-Engine auf FreshMarker scheiterte jedoch kläglich.
Die Bibliothek SpringDoc-OpenAPI ist ein gute Ergänzung für die eigene REST API, um die Endpunkte mit einer Dokumentation zu versehen. Die Bibliothek analysiert die @RestController annotierten Klassen und extrahiert Informationen zu Endpunkten, Parametern, Requests, Responses und Fehlercodes. Die gefundenen Informationen werden als OpenAPI Dokumentation im YAML oder JSON Format ausgegeben. Das klingt sehr gut, nur leider funktioniert es nicht ohne zusätzliche Eingriffe der Entwickler.
Die Dokumentation einer REST API sieht immer sehr schick aus. Ob es sich um eine interaktive Swagger Seite handelt oder um eine statische Darstellung eines anderen Tools, alle Endpoints, Parameter und Datentypen sind akkurat aufgelistet.