16. December 2020
by Andreas Grub | 629 words | ~3 min read
openapi spring spring boot library tools
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:
<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:
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.
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:
If you like to study examples, here’s a list:
@ExceptionHandlerMost 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.
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!
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.