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 specification[^openapi_spec] 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-plugin[^swagger-maven-plugin] 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 Boot[^spring-boot], 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

[^openapi_spec]: OAI/OpenAPI-Specification: The OpenAPI Specification Repository [^swagger-maven-plugin]: https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin [^spring-boot]: spring-projects/spring-boot: Spring Boot helps you to create Spring-powered, production-grade applications and services with absolute minimum fuss.