Spring Boot API Documentation

API documentation explains what an API offers: the addresses, the data each address accepts, and the replies it returns. Frontend developers, mobile developers, and testers rely on it to use the API correctly without reading the backend source code.

Writing documents by hand takes effort and drifts out of date as the code changes. Spring Boot solves the problem with OpenAPI, a standard format that describes an API. A library reads the controllers and generates the documents automatically, including a web page where anyone can try each request.

The Restaurant Menu Idea

A restaurant menu lists every dish, its description, and its price. Guests order with confidence and never need to visit the kitchen. API documentation serves as the menu for software. Clients read the list of available requests and order exactly what they need.

 Restaurant                       API
 ---------------------------------------------------
 Menu                  ====>     Swagger UI page
 Dish name             ====>     Endpoint address
 Ingredients list      ====>     Request body fields
 Photo of the dish     ====>     Sample response
 Waiter takes order    ====>     "Try it out" button

Key Terms

• OpenAPI is the standard format for describing REST APIs.
• Swagger UI is the interactive web page built from an OpenAPI description.
• springdoc-openapi is the library that connects Spring Boot to both.

Adding the Library

One dependency brings everything. Spring Boot 3 projects use the springdoc starter for Spring MVC.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Check the springdoc website for the newest version that matches your Spring Boot release.

Opening the Documentation

Restart the application and visit two addresses.

Address	Content
/v3/api-docs	Raw OpenAPI description in JSON
/swagger-ui.html	Interactive page with all endpoints

Every controller method appears on the page without any extra code. The page shows each method, address, parameter, and sample response.

Trying a Request

Swagger UI lets anyone test an endpoint from the browser.

 1. Open an endpoint, such as POST /api/books
 2. Click "Try it out"
 3. Edit the sample JSON body
 4. Click "Execute"
 5. Read the status code and response body

Testers save time because no separate tool is required.

Describing Endpoints Better

Annotations add friendly names and descriptions.

@RestController
@RequestMapping("/api/books")
@Tag(name = "Books", description = "Manage the book catalog")
public class BookController {

    @Operation(summary = "Find a book by id", description = "Returns one book or a 404 error")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book found"),
        @ApiResponse(responseCode = "404", description = "Book not found")
    })
    @GetMapping("/{id}")
    public ResponseEntity<Book> findOne(@PathVariable Long id) {
        // method body
    }
}

@Tag groups endpoints under a heading. @Operation explains one endpoint. @ApiResponse documents each possible result.

Describing Model Fields

public class Book {

    @Schema(description = "Unique book number", example = "101")
    private Long id;

    @Schema(description = "Book title", example = "Java Basics")
    private String title;
}

Examples appear in the Swagger UI and give readers realistic sample data.

Setting the API Title

A configuration bean sets the name, version, and contact for the whole API.

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI shopApi() {
        return new OpenAPI().info(new Info()
                .title("Book Shop API")
                .version("1.0")
                .description("Endpoints for managing books"));
    }
}

Useful Properties

springdoc.swagger-ui.path=/docs
springdoc.swagger-ui.operations-sorter=method
springdoc.packages-to-scan=com.estudy.shop.controller

The first line moves the page to /docs. The second sorts operations by HTTP method. The third limits scanning to one package.

Protecting Documentation in Production

Public documentation reveals every address in the system. Turn it off for production profiles unless the API is meant for outside developers.

# application-prod.properties
springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false

Projects that use Spring Security must allow the documentation paths for permitted users, or the page returns an access error.

Sharing the Documentation

The OpenAPI JSON file works as a contract between teams. Frontend developers import it into tools that generate typed client code. Testers import it into API testing tools and build test collections in minutes. Partner companies read the Swagger page to learn the API without a meeting. Update the file with each release so every reader sees the current behavior.

Best Practices

• Write short, clear summaries for every endpoint.
• Add realistic examples to model fields.
• List error responses along with success responses.
• Review the Swagger page after each release to confirm accuracy.
• Share the OpenAPI JSON file with client teams so they can generate client code automatically.

Generated documentation stays accurate because it comes straight from the code. Teams gain a shared, always-current reference that speeds up integration work.