1

I want to automate the generation of the API documentation in a spring-boot project, for which I see two options:

springdoc-openapi: works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations

OpenAPI Generator: generates code from an OpenAPI specification - at least the models and interfaces that will be implemented by the REST controllers

What I don't like about springdoc-openapi is that it pollutes the code with a bunch of annotations to describe the API.

On the other hand, I don't feel quite comfortable with OpenAPI Generator generating the models as a special requirement could come up where I'd have to customize the models in such a way that I wouldn't have control to do it.

I know there is not such thing as a best approach, but I'd like to know what other people think works best for them.

Carlos Gonzalez
  • 607
  • 1
  • 5
  • 13

1 Answers1

0

This is borderline opinion-based, but this is my take on this. I always use springdoc and rely on the generated documentation based on the annotations. The main reason is that it is easier to maintain the documentation if it is side by side with the code itself. If you change the code then it is easier not to forget to change the documentation. If you are worried about polluting the code, you could use an interface where you would add all the needed annotations, but then you would increase the possibility of forgetting to update the documentation.

The other approach I don't really like is because I prefer to have the code "generating" the documentation and not the other way around. To me, code is king and as such, it should lead the way.

João Dias
  • 16,277
  • 6
  • 33
  • 45