2

I am maintaining a Java application where we're constantly adding new features (changes in the api). I want to move towards using OpenAPI as a way to document the api. I see two schools of thought:

  1. Write the code, use some annotations to generate the OpenAPI spec.
  2. Write the OpenAPI, use it to generate some server code.

While both seem fine and dandy, the server code is simply stubbed out, and would then require a lot of manual plugging in of services. While that seems fine as a one time cost, then next time I update the interface, it seems to me the only two options are

  1. Generate them all again, re-do all the manual wiring.
  2. Hand edit the previously generated classes to match the new spec file (potentially introducing errors).

Am I correct with those options? If so, it seems that using the code to generate the api spec file is really the only sane choice.

piet.t
  • 11,718
  • 21
  • 43
  • 52
stupot
  • 81
  • 1
  • 4

1 Answers1

4

I would recommend an API First approach where you describe your API in the yaml file and generate with each new addition.

Now how do you deal with generator overwriting manual work? You could use inheritance to create models and controllers based on the code that is generated.

You can also use the .ignore file provided with the generator to if you want to be sure of files not being overwritten.

Viktor Baert
  • 686
  • 8
  • 22