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-generatorvsswagger-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.
Objective of the presentation:
My presentation should enable developers to choose on how to document their REST interfaces using OpenAPI tools, with giving much more concrete evidence and reasons than advices available online like https://swagger.io/blog/api-design/design-first-or-code-first-api-development/ (which has too many buzz words in my opinion).
Attendee pre-requisites - If none, enter "N/A":
Experience with Java and Swagger/OpenAPI is helpful, last years EclipseCon talk "OpenAPIs are everywhere" is a good introduction: https://www.eclipsecon.org/europe2018/sessions/openapis-are-everywhere, https://www.youtube.com/watch?v=-lDot4Yn7Dg
Comments Sign in to post comments
Link to the GitHub repo
Submitted by Peter Steiner on Thu, 2019-10-24 05:00
The code for my talk is on Github:
https://github.com/pe-st/apidocsLink to the slides
Submitted by Peter Steiner on Fri, 2019-10-25 00:35
I've added the links to the PDFs with the slides, one file with the slides for the 35 minutes talk and one file with all slides including extra material