OpenAPI 3 documentation for your Spring REST API with springdoc-openapi

Looking for the OpenAPI 3 compliant documentation for your Spring Boot-based project REST API?

As you know, there are many ways to achieve it (e.g. using the Springfox library). But which solution will be both integrated with the Spring ecosystem and OpenAPI 3 compliant?

Fortunately, the answer is springdoc-openapi. It’s the library that generates documentation almost automatically, without even providing configuration and thousands of cluttering annotations.

In this text, I’m going to show you how you can integrate your Spring Boot project with the springdoc-openapi library to generate nice API documentation which will be compatible with the OpenAPI 3 standard.

Quick introduction

Springdoc-openapi is yet another Swagger-based documentation generation library developed by the community. It’s dedicated to the Spring Boot applications, so it can be a good choice for your own Spring Boot-based app or microservice.

As an example, in this text, I’ll be using the Spring Boot application with REST API built and described previously on this blog.

Quick start

Using springdoc-openapi allows generating the REST API documentation generation really quick.

For the very basic version there’s no need to annotate the classes nor provide any configuration class. And it only needs a single dependency.

JSON-based documentation only: springdoc-openapi-webmvc-core

If there’s no need to have Swagger UI version of the documentation, then just the springdoc-openapi-web-mvc-core can be added as a dependency to the project.

If you’re using Gradle add the following line into your dependencies in build.gradle file:

dependencies {

	...
        implementation("org.springdoc:springdoc-openapi-webmvc-core:1.5.0")

}

If you’re using Maven, then add the following lines into dependencies in the project’s pom.xml file:

<dependencies>
    ...
       <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-webmvc-core</artifactId>
      <version>1.5.0</version>
   </dependency>
</dependencies>

At this point, the documentation in the JSON format can be found under /v3/api-docs.

There you go! If there’s no need to have user-friendly, rich UI documentation, then this JSON output can be pasted into the online Swagger Editor.

If the endpoint isn’t available right away, then consider checking the security configuration. Probably a few tweaks will be necessary to make it work.

JSON-based & Swagger UI – springdoc-openapi-ui

If the JSON format of the docs is not something you find very useful, then consider adding Swagger UI on top of that. This will bring a nice and clean user interface on top of the auto-generated documentation.

And again, no additional configuration is needed. Just replace the previous dependency with springdoc-openapi-ui.

Gradle dependency:

dependencies {
        ...
	implementation("org.springdoc:springdoc-openapi-ui:1.5.0")
}

Maven version:

<dependencies>
    ...
	

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.5.0</version>
   </dependency>
</dependencies>

Now just rebuild and rerun your project and that’s it. The documentation with the nice-looking Swagger UI should be available under /swagger-ui.html:

Spring Security configuration

Dependencies

If the application is using Spring Security then it’s necessary to use the springdoc-openapi-security dependency.

Gradle dependency:

  implementation("org.springdoc:springdoc-openapi-security:1.5.0")

Maven dependency:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-security</artifactId>
      <version>1.5.0</version>
   </dependency>

Exposing the endpoints

If there’s a need to expose the API documentation publicly, it can be done by relaxing the security config.

To make it open, consider adding the following rules to the Spring Security configuration class (Kotlin version):

    override fun configure(web: WebSecurity) {
        web.ignoring().antMatchers(
                "/v3/api-docs",
                "/swagger-ui.html",
                "/swagger-ui/**"
        )
    }

Of course, if you want to use it for your internal purposes, then these endpoints shouldn’t be exposed. Instead, proper security rules need to be applied. Yet still, after authentication, the docs will be available.

Kotlin support

The library has support for the Kotlin-based projects but to have better support of Kotlin types, it’s recommended to add the springdoc-openapi-kotlin dependency.

Gradle dependency:

  implementation("org.springdoc:springdoc-openapi-kotlin:1.5.0")

Maven dependency:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-kotlin</artifactId>
      <version>1.5.0</version>
   </dependency>

Documentation improvements

Package scanning

In most cases, we don’t like to expose all of the endpoints of our application. Apart from using Swagger‘s @Hidden annotation, there is a way to save your code from adding redundant annotations.

So if only certain packages should be scanned for annotations, just add this line in the application.properties:

springdoc.packagesToScan=net.mestwin.restapidemo.controller, net.mestwin.restapidemo.common.controller

Matching the specific paths

If there is a need to include only the specific paths in docs, then add this line:

springdoc.pathsToMatch=/auth, /tasks/**

Customize the output

If the auto-generated descriptions are not informative enough, then still Swagger 3 annotations can be used in the controller classes.

For instance, if the goal is to add the the description to the specific endpoint, just use @Operation annotation above the method declaration in the controller code:

 @PutMapping("/{id}")
    @Operation(summary = "Update task", description = "Updates task with given id")
    fun updateTask(@RequestBody request: TaskRequest, @PathVariable("id") id: String): ResponseEntity<Task> {
...
}

The result will be available in the documentation:

For more customization options look into the Swagger 3 reference.

Conclusions

As you can see, autogenerating documentation for your Spring REST API is not only possible but can be done quickly without the necessity of adding tons of annotations and deep-diving into the configuration.

Please note that for the sake of this short introduction I use a simple Spring Boot application. Most likely in bigger projects, you’ll need to provide more customizations.

The library has more features that I didn’t describe here. For instance Groovy language support, WebFlux-based APIs support, etc. For more detailed information take a look at its documentation

Needless to say, I switched from Springfox to springdoc-openapi in one of my projects too and I like it.

It’s worth giving it a try.

Resources

• Springdoc-openapi project documentation
• Springdoc-openapi project repository on GitHub
• Swagger 3 annotations documentation
• Migrating from Springfox to Springdoc-openapi, step-by-step guide
• Building simple REST API application with Spring Boot and Kotlin
• Springfox-based REST API documentation generation