Introduction

Spring Boot Actuator and Swagger-style API documentation solve different problems, and confusion usually starts when they are treated as the same kind of endpoint. Actuator exposes operational and health information for the running service, while Swagger or OpenAPI tooling documents the business API that consumers are expected to call.

What Each Tool Is For

Actuator is about runtime visibility. It can expose endpoints such as health, info, metrics, environment details, and readiness checks.

Swagger, or more accurately OpenAPI tooling in modern Spring projects, is about describing controller endpoints so developers can browse, test, and integrate with your API.

A practical rule is:

• use Actuator for operators and monitoring systems
• use OpenAPI or Swagger UI for application consumers

Keeping those responsibilities separate makes the service easier to secure and reason about.

Adding Actuator

A minimal Spring Boot setup adds the Actuator starter and then explicitly exposes the endpoints you want.

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-actuator</artifactId>
4</dependency>

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=when_authorized

With that configuration, the service can expose endpoints under /actuator.

Adding OpenAPI Documentation

In current Spring Boot projects, springdoc-openapi is a common choice.

1<dependency>
2    <groupId>org.springdoc</groupId>
3    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
4    <version>2.8.5</version>
5</dependency>

A normal controller then appears in the generated documentation:

1@RestController
2@RequestMapping("/api/books")
3class BookController {
4
5    @GetMapping
6    public List<String> listBooks() {
7        return List.of("DDD", "Clean Code");
8    }
9}

Swagger UI is then available from the OpenAPI tooling path, while operational endpoints continue to live under /actuator.

Should Actuator Endpoints Appear In Swagger

Usually, no. Most teams intentionally keep Actuator endpoints out of public API documentation because they are not part of the external application contract. They are operational surfaces, often protected differently, and may be exposed only internally.

If you document them at all, do so deliberately and with security in mind. The default architecture should treat them as management endpoints, not product endpoints.

Use A Separate Management Port When Needed

For production systems, it is common to isolate Actuator from the main application port.

1server.port=8080
2management.server.port=8081
3management.endpoints.web.base-path=/actuator
4management.endpoints.web.exposure.include=health,info,prometheus

This separation helps route monitoring traffic differently and reduces the chance of accidentally exposing sensitive management data through the same public entry point as customer-facing APIs.

Security Matters

Actuator endpoints can reveal internal state. Even health details may contain dependency information that you do not want public.

1@Bean
2SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
3    http
4        .authorizeHttpRequests(auth -> auth
5            .requestMatchers("/actuator/health", "/actuator/info").permitAll()
6            .requestMatchers("/actuator/**").hasRole("OPS")
7            .anyRequest().authenticated()
8        )
9        .httpBasic();
10    return http.build();
11}

That kind of split access is common: minimal public health visibility, stricter access for the rest.

Common Integration Pattern

The clean pattern is to let OpenAPI document controllers under your application namespace and let Actuator handle management endpoints under /actuator. Monitoring tools scrape Actuator; frontend or partner developers use Swagger UI.

That design prevents you from overloading a single tool with responsibilities it was not meant to carry.

Common Pitfalls

The most common mistake is exposing every Actuator endpoint publicly because the service "needs monitoring." Another is expecting Swagger UI to automatically document management endpoints in a useful or secure way. Teams also sometimes forget that Actuator exposure and Actuator security are separate concerns; an endpoint can be exposed without being appropriately protected. Finally, old blog posts still refer to Springfox Swagger setups that do not match modern Spring Boot versions, so choose examples that match your dependency stack.

Summary

• Actuator is for management and observability; Swagger or OpenAPI is for API documentation.
• Keep operational endpoints and business API endpoints conceptually separate.
• Expose only the Actuator endpoints you actually need.
• Use springdoc-openapi or similar tooling for controller documentation in modern Spring Boot projects.
• Secure Actuator endpoints independently, especially in production.