r/SpringBoot • • Sep 28 '26

Question How much Swagger/OpenAPI documentation is actually needed in a Spring Boot project?

I'm working on a Spring Boot e-commerce project and I'm currently documenting my APIs using Swagger/OpenAPI.

For example, my controller currently looks something like this:

(
    summary = "Create a new category",
    responses = {
        .swagger.v3.oas.annotations.responses.ApiResponse(
            responseCode = "201",
            description = "Category created successfully"
        ),
        .swagger.v3.oas.annotations.responses.ApiResponse(
            responseCode = "409",
            description = "Category already exists"
        )
    }
)
("/admin/categories")
u/SecurityRequirement(name = "bearerAuth")
public ResponseEntity<ApiResponse<CategoryResponseDto>> addCategory(
          CategoryRequestDto dtoRequest) {

    CategoryResponseDto categoryResponseDto =
            categoryService.addCategory(dtoRequest);

    return ResponseEntity
            .status(HttpStatus.CREATED)
            .body(ApiResponse.success(
                    categoryResponseDto,
                    HttpStatus.CREATED.value()
            ));
}

The problem is that if I also start adding u/Parameter, more u/ApiResponse, u/Schema, u/ExampleObject, etc., the controller becomes very large and difficult to read.

I'm trying to find a good balance between proper API documentation and clean maintainable code.

For example, would something this simple be considered enough?

(summary = "Create a new category")
("/admin/categories")
u/SecurityRequirement(name = "bearerAuth")

Or should I at least document the success/error responses?

Also, how do you normally handle common responses such as:

  • 400 Bad Request

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found

  • 409 Conflict

Do you document these on every endpoint, or handle them globally?

If you work professionally with Spring Boot/OpenAPI, what approach do you use to keep Swagger documentation useful without making controllers huge?

I'm particularly interested in how this is handled in real-world/company projects rather than tutorial projects.

16 Upvotes

Duplicates