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:

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-plugin2 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

         

YourKit
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