Using Springdoc-openapi with resteasy-spring-boot
By Wei Nan Li | November 15, 2024
Recently there is a request in the resteasy-spring-boot
community:
It’s an interesting request because I haven’t dug into this kind of usage before. I spent some time investigating the topic, and I’d like to share what I have learned in this blog post.
The OpenAPI is a specification1 by itself, and it doesn’t enforce its implementations. There are currently two major implementors of the specification. One is the MicroProfile OpenAPI Specification and the other one is the Swagger OpenAPI Specification - Version 3.1.0. These two specifications define their own Java annotations, service provider interfaces, and configurations.
Because the above two implementors just define the interfaces for the OpenAPI specification, they still need projects to implement their interfaces. So on MicroProfile OpenAPI side, the smallrye-open-api project implements the MicroProfile OpenAPI Specification(which means it implements the interfaces defined by the specification), on the other side, the Swagger project implements its specification. But they share the same format of the OpenAPI document defined by the OAI/OpenAPI-Specification
ultimately.
The WildFly and Quarkus communities support the MicroProfile OpenAPI by default. I have written a blog post before describing the usage of MicroProfile OpenAPI with RESTEasy and a provisioned WildFly server:
For Quarkus, here is a blog post that shows the usage of the built-in MicroProfile OpenAPI in Quarkus:
Besides the above standard usages, here is an excellent presentation that shows the mixture usages of the MicroProfile OpenAPI and Swagger with Quarkus:
- MicroProfile OpenAPI - code first or design first? / Relative demo project of the presentation: https://github.com/pe-st/apidocs
The above example uses a mixture of the Swagger and MicroProfile OpenAPI: It uses the Swagger annotations in the code, and it uses the swagger-maven-plugin
2 to generate the OpenAPI documentation. Because the generated OpenAPI documentation files(in both json
and yaml
formats) follow the OpenAPI specification, these generated files can be consumed by the MicroProfile OpenAPI module in the Quarkus. So the API information can be exposed during the server runtime.
For Spring Boot3, it has a third-party project called springdoc-openapi. This project integrates Swagger with Spring Boot. It doesn’t use the MicroProfile OpenAPI in both generation and during server runtime, and this is what I want to try to integrate into resteasy-spring-boot
and deploy it into a provisioned WildFly server to see if it works. Finally, I made this pull request:
In the above pull request, the springdoc
is added to the example, and the example is configured to be deployed into a provisioned WildFly server. In the example, the Swagger annotations are used in the resource classes, and the swagger-maven-plugin
is used to generate the OpenAPI document files.
In the example, the microprofile-openapi
is not added to the provisioned WildFly server, and the springdoc
is serving the Swagger UI page during server runtime. One thing to note is that it seems the automated document generation doesn’t work with resteasy-spring-boot
, so I disable it in the configuration file application.yaml
:
springdoc:
swagger-ui:
url: "/openapi.json"
enabled: false
In the above configuration, I also configured the swagger-ui
to use the OpenAPI document file generated by the swagger-maven-plugin
.
Above are what I have learned during the working process of this task, and you can play with the example if you are interested in this topic too.
References
-
OAI/OpenAPI-Specification: The OpenAPI Specification Repository ↩
-
https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin ↩
-
spring-projects/spring-boot: Spring Boot helps you to create Spring-powered, production-grade applications and services with absolute minimum fuss. ↩
Useful Links
YourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor