Best way to generate Swagger API? i.e. codegen vs swagger editor (Spring Boot API)

user_9796935 0
Viewed 1219

I'm working on an API (Spring Boot) that is somewhat legacy - it is using openapi version 2.0 and it also uses the swagger-codegen-maven-plugin plugin in the pom.xml.

I recently did a LinkedIn learning course where we used the Swagger Editor (locally using Docker) to write the api specification (openapi 3.0) and "export" the Server Stub in any language of your choosing, in this case Java Spring. I noticed the API classes that the Controllers implement were already generated in this stub. However, when using the swagger-codegen-maven-plugin, these interfaces aren't generated until you compile the project (mvn install), the same goes with the schemas for any data structures you define, for say, your request body in the "definitions" section of the swagger yaml.

I wanted to inquire what is the preferred method here to build the API - is it to use the Swagger editor via the web GUI or locally and write the specification in YAML then export the Server Stub in the language/framework of your choice OR is it to manually write some of the classes locally (Even if you add the swagger yaml, it still looks like you have to write the code for the Controllers etc.. using this method, please correct me if I'm wrong) i.e. IntelliJ using Spring, then add the swagger-codegen-maven-plugin to your project and have it generate the interfaces/concrete classes for you?

swagger-codegen swagger maven spring java
1 Answers

I prefer to use the Maven plugin.

There is nothing wrong with generating your server stub during the compile phase of the Maven life cycle: you run it, you get your stubs and you start working with them.

The Maven plugin has the advantage that you can configure the output of the generator: for example you can set up a package name, a suffix or prefix for model names, whether you want to generate only interfaces or also a stub implementation.

Here is the full list of the maven plugin configurations and here you can find Spring specific options. With the Swagger web generator, as far as I know, you can't configure anything.

Only thing to remember when using the maven plugin is to not modify manually the generated code, otherwise every time you run it again, you will lose your manual changes. So your actual implementation code will need to implement the generated API interface or extends the generated API controller. Or even better generate the code with the delegatePattern option set to true, and implement the generated delegate interface.

user_8391580
Related