RESTEasy > Blogs > Using Springdoc-openapi with resteasy-spring-boot

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:

• Can not integrate with spring doc · Issue #349 · resteasy/resteasy-spring-boot

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¹ 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:

• Using MicroProfile OpenAPI With RESTEasy

For Quarkus, here is a blog post that shows the usage of the built-in MicroProfile OpenAPI in Quarkus:

• MicroProfile OpenAPI for everyone

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² 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³, 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:

• Can not integrate with spring doc #349 by liweinan · Pull Request #350 · resteasy/resteasy-spring-boot

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