🧠 A smart, automated way to document your Spring Boot APIs.
- 🔧 Compatibility
- 🚀 Introduction
- 💡 Why DocFlow?
- 💥 Problem & 🌱 The Solution
- 🎯 Features
- 🛠️ Installation
- 🚀 Sample Projects
- ⚡ Quick Start
- 🏷️ Annotations & Supported HTTP Status Codes
- 🔒 Smart Security (JWT Authentication)
- 🌐 Internationalization (i18n)
- 🗺️ Roadmap
- 📜 License
- ⭐ Support
- ✍️ Author
| Component | Supported Version |
|---|---|
| Java | 17+ |
| Spring Boot | 3.4.0+ |
✅ Tested on Spring Boot 3.4.x, 3.5.x and 4.0.0.
❌ Versions prior to Spring Boot 3.4.0 are not supported.
DocFlow is a SpringDoc OpenAPI support library that simplifies endpoint documentation by automating summaries and descriptions and standardizing error schemes. With native support for internationalization (i18n), DocFlow allows your API to communicate with the world in multiple languages without any extra effort.
DocFlow eliminates the need to write repetitive text in OpenAPI annotations. Through automatic inferences and custom annotations, you keep your code clean and your Swagger documentation professional, following industry best practices.
DocFlow was created to solve three common problems in Spring Boot APIs:
- Excessive Swagger/OpenAPI boilerplate
- Repetitive HTTP response documentation
- Lack of standardized documentation across projects
By leveraging conventions and automation, DocFlow allows developers to focus on business logic instead of documentation maintenance.
Have you ever felt like you’re writing more Swagger annotations than business logic? Excessive OpenAPI configuration wastes time and undermines the readability of your Java code. The common workaround of creating an interface just to “hide” the annotations from the controller is a stopgap that creates another problem: an explosion of duplicate files in your project.
|
Excessive boilerplate, cluttered endpoints, and poor readability. 
|
Clean code, zero boilerplate, and automatic documentation based on conventions. 
|
- Reduced Swagger Boilerplate: Say goodbye to endless annotations cluttering your controllers.
- Automatic OpenAPI Documentation: Generates full, compliant OpenAPI specs seamlessly.
- Smart Security Inference: Automatically reads Spring Security annotations (e.g.,
@PreAuthorize) to secure endpoints. - Zero-Config JWT Auth: Instantly configures Bearer token authentication in Swagger UI without manual schemas.
- Smart HTTP Response Inference: Automatically detects and maps your endpoint response types.
- Automatic 200 / 204 Detection: Smart recognition of content return vs. empty success statuses.
- Convention-Based Descriptions: Generates clear, human-readable endpoint documentation by default.
- Spring Boot Auto-Configuration: Plug-and-play setup with zero manual bean configuration required.
- Flexible YAML Configuration: Easily customize global behaviors and metadata via
application.yml. - OpenAPI Schema Customization: Fully extend, override, or tweak generated schemas when needed.
Add the DocFlow starter to your project configuration:
<dependency>
<groupId>io.github.docflow-lib</groupId>
<artifactId>docflow-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>implementation 'io.github.docflow-lib:docflow-spring-boot-starter:1.0.0' |
| Property | Description |
|---|---|
| docflow.title | OpenAPI title |
| docflow.description | OpenAPI description |
| docflow.version | API version |
| docflow.default-error-schema | Global error response DTO |
| docflow.security.enabled | Activate the security module (Spring Security). |
| docflow.security.scheme-name | Text that appears on the Swagger button |
Configure your project properties by adjusting the paths and packages to match your own project structure. Choose your preferred format below:
springdoc:
swagger-ui:
path: /swagger-ui.html # Your custom Swagger UI URL path
api-docs:
path: /v3/api-docs # Your custom OpenAPI JSON path
packages-to-scan: com.yourcompany.yourproject.controller # Package where your controllers are located
remove-broken-reference-definitions: false
docflow:
title: "Your API Title"
description: "Your API Description"
version: "1.0.0"
default-error-schema: com.yourcompany.yourproject.exception.StandardError # Path to your global error DTO# SpringDoc Setup
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/v3/api-docs
springdoc.packages-to-scan=com.yourcompany.yourproject.controller
springdoc.remove-broken-reference-definitions=false
# DocFlow Setup
docflow.title=Your API Title
docflow.description=Your API Description
docflow.version=1.0.0
docflow.default-error-schema=com.yourcompany.yourproject.exception.StandardError |
To help you get started quickly, we provide complete, functional, and verified sample applications for both build tools. You can explore the source code to see DocFlow in action:
| Build Tool | Project Link | Key Features Demonstrated |
|---|---|---|
| Maven 🛠️ | docflow-maven-sample | Spring Boot 3.4.0+, Spring Security, Automated Swagger OpenAPI generation |
| Gradle 🐘 | docflow-gradle-sample | Multi-platform build integration, Zero-Config documentation routing |
- Clone this repository.
- Navigate to the desired sample folder (
examples/docflow-maven-sampleorexamples/docflow-gradle-sample). - Run the application:
- For Maven:
mvn spring-boot:run - For Gradle:
./gradlew bootRun
- For Maven:
- Access the interactive documentation at: Click here or http://localhost:8080/swagger-ui.html
Docflow offers two flexible ways to document your methods: automatic and manual.
In this mode, you just need to enter the annotation. Docflow automatically generates the information based on the method name.
@RestController
@RequestMapping("/users")
@ApiDocController // <- DocFlow Annotations
public class UserController {
@PostMapping
@ApiDocPost // <- DocFlow Annotations
public ResponseEntity<UserResponse> createNewUser(@RequestBody UserCreateDTO request) {
return ResponseEntity.status(HttpStatus.CREATED).body(service.create(request));
}
}
|
If you need more details or a customized description, you can enter the information directly in the note.
@RestController
@RequestMapping("/users")
@ApiDocController(
tagName = "Users", // Optional
tagDescription = "User management endpoints" // Optional
)
public class UserController {
@PostMapping
@ApiDocPost(
summary = "Create a new user", // Optional
description = "Registers a new user in the system with basic permissions." // Optional
)
public ResponseEntity<UserResponse> createNewUser(@RequestBody UserCreateDTO request) {
return ResponseEntity.status(HttpStatus.CREATED).body(service.create(request));
}
}
|
| Note | HTTP Method | Standard HTTP Codes | Status Description |
|---|---|---|---|
@ApiDocGet |
GET |
200, 401, 403, 404, 500 | Success (OK), Unauthorized, Forbidden, Not Found, Internal Error. |
@ApiDocPost |
POST |
201, 400, 401, 403, 409, 422, 500 | Created, Invalid Request, Unauthorized, Forbidden, Conflict, Unprocessable Entity, Internal Error. |
@ApiDocPut / @ApiDocPatch |
PUT / PATCH |
200/204, 400, 401, 403, 404, 422, 500 | Success/No Content, Invalid Request, Unauthorized, Forbidden, Not Found, Unprocessable Entity, Internal Error. |
@ApiDocDelete |
DELETE |
204, 401, 403, 404, 500 | No Content, Unauthorized, Forbidden, Not Found, Internal Error. |
| Annotation | Where to apply? | When to use? |
|---|---|---|
@ApiDocController |
On the Controller class | In classes annotated with @RestController or @Controller. |
@ApiDocGet |
On the method | In HTTP GET methods (@GetMapping). |
@ApiDocPost |
On the method | In HTTP POST methods (@PostMapping). |
@ApiDocPut |
On the method | In HTTP PUT methods (@PutMapping). |
@ApiDocPatch |
On the method | In HTTP PATCH methods (@PatchMapping). |
@ApiDocDelete |
On the method | In HTTP DELETE methods (@DeleteMapping). |
DocFlow features a security inference engine that draws the padlocks in Swagger and creates the Login button automatically, without cluttering your code with verbose OpenAPI annotations.
Just turn on security in your application.yml/.properties. The library natively configures the Bearer Token (JWT) format:
docflow:
security:
enabled: true
scheme-name: "API Authentication" # Optional: Text that appears on the Swagger buttondocflow.security.enabled=true
docflow.security.scheme-name=API Authentication # Optional: Text that appears on the Swagger button// 🔓 Free Route: DocFlow notices the lack of annotations and leaves the documentation public.
@GetMapping
public List<User> list() { ... }
// 🔒 Protected Route: DocFlow detects @PreAuthorize and places the padlock automatically!
@PostMapping
@PreAuthorize("hasRole('ADMIN')")
public User create() { ... }
|
docflow:
security:
enabled: false
scheme-name: "API Authentication" # Optional: Text that appears on the Swagger buttondocflow.security.enabled=false
docflow.security.scheme-name=API Authentication # Optional: Text that appears on the Swagger button// 🔓 Free Route: DocFlow notices the lack of annotations and leaves the documentation public.
@GetMapping
public List<User> list() { ... }
// 🔒 Protected Route: DocFlow detects @PreAuthorize and places the padlock automatically!
@PostMapping
@PreAuthorize("hasRole('ADMIN')")
public User create() { ... }
|
One of DocFlow's most powerful features is its native multi-language support. The documentation dynamically adapts based on the user's browser language context.
By default, if a language is not specified or supported, it fallbacks to English.
|
|
No extra configuration is required. DocFlow automatically detects the Accept-Language headers and translates the standard error descriptions on the fly.
|
|
|
|
|
|
|
|
If DocFlow helps your project, consider giving it a star on GitHub.
Mateus Silva
