How to generate an OpenAPI from a Spring app without running the app?

Question

I can run a Spring Boot application and then use the springdoc-openapi-maven-plugin artifact to generate an OpenAPI spec.

However, is there also a way to generate the spec without running the application first?

I currently want to generate the spec in a GitHub Action and a direct way would simplify this a lot.

Answer 1

you can use swagger editor: https://editor.swagger.io/

It allows you to write a json/yaml with your specifications and at the same time you can view the result.

Also, in the upper part there are 2 features, which allow you to generate the code based on the json/yaml made. For example you can create a spring application with all the endpoints you go to specify in your json/yaml ( server).

But you can also generate HTML. (Client)

Answer 2

To generate OpenAPI with springdoc-openapi-maven-plugin you can add integration-test goal and run mvn verify to generate json/yaml spec after tests. (https://springdoc.org/plugins.html)

Unfortunately, it starts your app and calls OpenAPI endpoint. If your app has startup dependencies (configuration properties, database, etc...) then you have two options:

1. Run your dependencies in docker container before running mvn verify. Also you need to configure your properties to use docker hosts and ports.

2. More elegant solution is to create different profile, for example openapi and disable database autoconfigurations by using @EnableAutoConfiguration(exclude = ...). To disable component beans, you can use @ComponentScan and custom TypeFilter which would for example completely exclude Service and Configuration layer from injecting to a context (Because only Controller layer is needed to generate OpenAPI spec). If you will exclude beans which Controller layer depends on then you need to make them as non- required. You can do it by adding @Autowired(required = false) for each declaration or it is better to do it for all excluded beans and only for openapi profile, for this you can use QualifierAnnotationAutowireCandidateResolver and override isRequired method where you can specify all your excluded beans for which you need to return false.

Example: https://github.com/ivan-zaitsev/java-spring-example/tree/main/isolated-context

Answer 3

If you are using Intellij Idea as IDE you can generate docs manually.

View -> Tool windows -> Endpoints
On Endpoints tab using right-click generate endpoint for whole project or specific endpoint

Full information: https://www.jetbrains.com/help/idea/openapi.html#create-spec