Duration: 36:07

658 views

4

Discussions on the best techniques can often get heated, but one consensus is not disputed: all developers, architects and POs like it when a service provides a browser interface like Swagger UI for its interface documentation. So your goal is to have an OpenAPI document (an openapi.yaml file) for the service you're about to write. To help you decide if you should write it yourself and generate the Java classes out of it (design-first approach) or let it generate from your annotated code (code-first approach), I'll show you code examples and tell about my learnings, e.g.:

code-first: the generated OpenAPI document differs heavily between different generators (e.g. OpenLiberty vs Quarkus)
design-first: similarly, the generated code has some important differences, e.g. when using openapi-generator vs swagger-codegen
if you want to avoid maintaining the same documentation/code in different places (Javadoc, OpenAPI annotations, Bean Validation annotations) you'll probably want to have a deeper look at the design-first approach
All the examples will be available in a Github repository.

Slides (External URL):
https://github.com/pe-st/apidocs/raw/master/MicroProfile-OpenAPI-slides-eclipsec...
https://github.com/pe-st/apidocs/raw/master/MicroProfile-OpenAPI-all-slides.pdf

Speaker(s):
Peter Steiner