Documenting functional REST endpoints with springdoc-openapi

What is springdoc?
springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.Automatically generates documentation in JSON/YAML and HTML format APIs. This documentation can be completed by comments using swagger-api annotations.

What is Spring Web Flux?
Spring WebFlux is a web framework that’s built on top of Project Reactor, to give you asynchronous I/O, and allow your application to perform better.

Demo Application

In order to get better acquainted with these technologies, we will develop Spring Boot WebFlux application with CRUD operations and use swagger-api annotations to documenting functional REST endpoints

Spring Boot Application setup

• Initialize Spring Boot WebFlux project via Spring initializr
• Add Springdoc OpenAPI WebFlux UI dependency to build.gradle.

Multiple RouterFunction router setup

• Setup router with multiple router functions.

Implement Annotation creation for single route

• Create annotation with @RouterOperations description inside
• operationId is required field
• path is optional field

Endpoint Documentation for RouterFunction with single Route

• Mark router function with@AddPlayerApiInfo description inside

Single RouterFunction router setup

• Setup router with single router function with multiple routes.

Annotation creation for multiple routes

• It will be look kind of verbose if you will add all descriptions there , but it’s works fine.
• You need specify path for endpoint description

Endpoint Documentation for RouterFunction with multiple routes

• Mark router function with@CommonApiInfo description inside

Run application and verify documentation

• The Swagger UI page will then be available at http://{server}:{port}/swagger-ui.html

• Documentation will be available here: http://{server}:{port}/v3/api-docs
• Viola!

Source code can be found on GitHub:

GitHub - klindziukp/spring-doc-webflux: Spring Doc WebFlux project for Dandelion Tutorials