16. December 2020

Generating OpenApi specification from Spring Boot

by Andreas Grub | 634 words | ~3 min read

openapi spring spring boot library tools

openapi-lib-title.png

An OpenAPI specification file is a document describing the (HTTP) API endpoints of your application. Based on the specification, you can generate clients directly interacting with your application for almost any programming languages. For example, this is convenient for frontend development using the application’s backend API.
You may know it also as “Swagger”, which is the former name for the OpenAPI specification version 2. It has now become an open initiative to promote well-documented application APIs everywhere.

Today, we proudly present a new library for generating OpenAPI v3 specifications from your running Spring Boot application. The development was supported by QAware and is now released on GitHub.

This post highlights some features what this library can do. You can also just skip reading and just include its Spring Boot Starter to give it a shot:

1
2
3
4
5

<dependency>
    <groupId>de.qaware.tools.openapi-generator-for-spring</groupId>
    <artifactId>openapi-generator-for-spring-starter</artifactId>
    <version>1.0.1</version>
</dependency>

After opening /swagger-ui relative to your application’s endpoint in your browser, you should see something like:

Swagger UI of WebMVC demo

If you don’t see that, please open an issue. The above screenshot is taken from the included WebMVC demo application, but it works also just the same for WebFlux.

Why this library?

If you like to read only a few sentences why:

The library was built from ground up without any prerequisite except Spring Core. It natively supports WebMVC and WebFlux and is customizable to any extent thanks to Spring Boot auto-configurations. The library adheres to as many “Spring best practices” as known to the authors and treats code quality and exhaustive testing as a first class citizen.

If you like a list of some (arbitrarily relevant) bullet points of reasons, here’s one:

  • Correctly handles Schema building for self-referencing (nested) types
  • Ships Swagger UI out-of-the-box without triggering Spring Boot’s WebJar auto-configuration
  • Supports WebFlux including Router Functions and WebMVC Handler Methods
  • Supports Content Negotiation within the limits of the OpenAPI specification
  • Is highly customizable using custom beans for filtering and adapting the generated model
  • Support JSON and (optional) YAML output of the specification

If you like to study examples, here’s a list:

Most of the above links point to integration tests of the library, which can be run as standalone Spring Boot applications.

If you like to read why not any other library, read the next paragraph.

Why not SpringFox or SpringDoc?

There have already been other libraries with a similar focus on the market, such as Spring Fox and Spring Doc.

Before starting this library, we have widely used Spring Fox in our projects but got more and more constrained by the library. Also, maintenance and inclusion of pull requests seemed to have died down in 2019, although it got more lively recently.

Spring Doc seemed to be the perfect alternative about a year ago, and one author of this new library actually tried to contribute and adapt the existing one. However, we found more and more that some useful things are not so easy to do even with Spring Doc, and started developing our own. It was also just a fun experience!

Acknowledgements

This library was developed by Dirk Kröhan and Andreas Grub and was gratefully supported by QAware by allowing us to do that during paid working hours. It was finally released thanks to the QAgarage day end of November, where many of us took the chance to do useful stuff but never found time for it outside the usual project churn.

The Latest Posts