Practical examples of integrating Swagger with Spring Boot applications

Real examples of integrating Swagger with Spring Boot applications

Let’s start where most teams actually start: a simple Spring Boot REST API that needs human-friendly documentation. From there, we’ll layer on the patterns you see in production systems.

The best examples of integrating Swagger with Spring Boot applications usually share three traits:

• They rely on springdoc-openapi rather than the older springfox libraries.
• They keep annotations close to the controller methods so docs stay in sync with code.
• They plug into the build and CI pipeline so the OpenAPI spec is always up to date.

Example of a minimal Spring Boot 3 + Swagger setup

Imagine a small CustomerService built with Spring Boot 3 and Java 17. You want a quick way for QA and frontend devs to explore endpoints without reading the code.

In 2024, the standard way is to use springdoc-openapi:

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

With that starter, Spring Boot auto-configures:

• An OpenAPI 3 spec at /v3/api-docs
• Swagger UI at /swagger-ui.html (or /swagger-ui/index.html)

A minimal controller that documents itself might look like this:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/customers")
@Tag(name = "Customers", description = "Customer management APIs")
public class CustomerController {

    @GetMapping("/{id}")
    @Operation(summary = "Get customer by ID", description = "Returns a single customer by its ID")
    public CustomerDto getCustomer(@PathVariable Long id) {
        // ... fetch from service
    }
}

This is the baseline example of integrating Swagger with Spring Boot applications: one dependency, a couple of annotations, and Swagger UI is live.

Examples of integrating Swagger with Spring Boot applications in real teams

In real projects, the Swagger story rarely ends with a single controller. Here are several examples of integrating Swagger with Spring Boot applications the way teams actually do it.

1. Documenting a public-facing API for external partners

Picture a logistics company exposing shipment tracking APIs to third-party retailers. They need:

• Clean, branded Swagger UI for partners
• Clear request/response models
• Contact and license info in the OpenAPI spec

A common pattern is a central OpenAPI config:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI shipmentOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Shipment Tracking API")
                .description("APIs for querying shipment status and events")
                .version("v1.2.0")
                .contact(new Contact()
                    .name("API Support")
                    .email("api-support@example.com"))
            );
    }
}

This example of integrating Swagger with Spring Boot applications focuses on external consumption: the OpenAPI document doubles as a contract with partners and plugs into their client generators.

2. Grouping endpoints for a microservices-style architecture

Many teams end up with a “gateway” Spring Boot app that proxies to multiple back-end services. One of the best examples of integrating Swagger with Spring Boot applications in this setup is to group APIs by domain in Swagger UI.

Using springdoc, you can define groups:

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerGroupsConfig {

    @Bean
    public GroupedOpenApi customerApi() {
        return GroupedOpenApi.builder()
            .group("customers")
            .pathsToMatch("/api/customers/**")
            .build();
    }

    @Bean
    public GroupedOpenApi ordersApi() {
        return GroupedOpenApi.builder()
            .group("orders")
            .pathsToMatch("/api/orders/**")
            .build();
    }
}

Swagger UI now shows separate tabs for customers and orders. For developers, this is one of the most practical examples of integrating Swagger with Spring Boot applications because it keeps large systems navigable.

Securing Swagger UI: examples include OAuth2 and role-based access

By 2024, almost every company is more cautious about exposing internal API docs. Swagger UI becomes a security concern if left open to the internet.

3. Hiding Swagger UI in production behind Spring Security

A common example of integrating Swagger with Spring Boot applications securely is to restrict Swagger UI to internal roles.

With Spring Security 6:

import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**")
                    .hasRole("API_DOCS")
                .anyRequest().authenticated()
            )
            .oauth2Login();

        return http.build();
    }
}

In many enterprises, examples of integrating Swagger with Spring Boot applications look exactly like this: Swagger is available, but only to engineers with a specific role.

4. Integrating Swagger with Spring Security OAuth2 for external clients

For public APIs using OAuth2, you can document security schemes directly in OpenAPI so clients see how to authenticate.

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;

@Bean
public OpenAPI securedOpenAPI() {
    final String securitySchemeName = "oauth2Auth";

    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
        .components(new Components()
            .addSecuritySchemes(securitySchemeName,
                new SecurityScheme()
                    .type(SecurityScheme.Type.OAUTH2)
                    .flows(/* your OAuth2 flows here */)));
}

This example of integrating Swagger with Spring Boot applications aligns the docs with the actual security configuration, which reduces support tickets from confused API consumers.

Contract-first workflows: generating Spring Boot code from OpenAPI

Not every team writes controllers first and documents them later. An increasingly popular pattern in 2024–2025 is contract-first: define the OpenAPI spec, generate Spring Boot interfaces, then implement.

5. Using OpenAPI Generator with Spring Boot

One of the best examples of integrating Swagger with Spring Boot applications in a contract-first world uses OpenAPI Generator in the build.

In pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>7.8.0</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/openapi.yml</inputSpec>
            <generatorName>spring</generatorName>
            <apiPackage>com.example.api</apiPackage>
            <modelPackage>com.example.model</modelPackage>
            <generateSupportingFiles>false</generateSupportingFiles>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

You maintain openapi.yml as the single source of truth. The plugin generates controller interfaces that you implement. This is one of the clearest examples of integrating Swagger with Spring Boot applications where the OpenAPI definition drives the code, not the other way around.

For more background on API design-first approaches, the OpenAPI Initiative’s site at openapis.org is a solid reference.

Documenting errors, versioning, and pagination

The difference between toy demos and production APIs is in the details: error models, pagination, and versioning. Real examples of integrating Swagger with Spring Boot applications always address these.

6. Standardized error responses

A healthcare startup building FHIR-like APIs might define a shared error model and annotate it across endpoints. While FHIR itself is documented at hl7.org, the same pattern applies to any industry.

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@Operation(summary = "Get order by ID")
@ApiResponse(
    responseCode = "200",
    description = "Order found"
)
@ApiResponse(
    responseCode = "404",
    description = "Order not found",
    content = @Content(schema = @Schema(implementation = ErrorResponse.class))
)
@GetMapping("/api/orders/{id}")
public OrderDto getOrder(@PathVariable String id) {
    // ...
}

This example of integrating Swagger with Spring Boot applications shows how to make error handling visible and predictable for clients.

7. API versioning in the path and in OpenAPI

Another pattern you see often in 2024: versioned base paths like /api/v1 and separate OpenAPI groups per version.

@Bean
public GroupedOpenApi v1Api() {
    return GroupedOpenApi.builder()
        .group("v1")
        .pathsToMatch("/api/v1/**")
        .build();
}

@Bean
public GroupedOpenApi v2Api() {
    return GroupedOpenApi.builder()
        .group("v2")
        .pathsToMatch("/api/v2/**")
        .build();
}

For teams running multiple API generations in parallel, this is one of the more practical examples of integrating Swagger with Spring Boot applications: each version has its own documented surface area, and Swagger UI makes it trivial to compare.

CI/CD and governance: how Swagger fits into modern pipelines

In 2024–2025, the conversation around Swagger and Spring Boot is less “how do I get the UI running?” and more “how do I keep my API quality high over time?”

8. Validating OpenAPI specs in CI

Mature teams treat the OpenAPI definition as a testable artifact. A very common example of integrating Swagger with Spring Boot applications in CI is:

• Generate the OpenAPI spec on build (mvn test or mvn verify).
• Run a linter or validator (for example, Spectral) against /v3/api-docs output.
• Fail the build if breaking changes appear without a version bump.

This keeps your Swagger docs from drifting away from reality and enforces standards like consistent response codes and pagination parameters.

For teams in regulated industries (healthcare, finance), this pattern aligns well with guidance around software validation and documentation quality. While not Swagger-specific, organizations like the U.S. National Institute of Standards and Technology at nist.gov publish general software engineering and validation resources that many compliance teams reference.

FAQ: examples of real-world Swagger + Spring Boot questions

Q1. What are some real examples of integrating Swagger with Spring Boot applications in production?
Common examples include: internal developer portals where multiple Spring Boot services publish their Swagger docs; public partner APIs with branded Swagger UI; and regulated-industry platforms that use OpenAPI as a signed contract with external integrators.

Q2. Can you give an example of using Swagger with Spring Boot and Kotlin?
Yes. The same springdoc-openapi starter works with Kotlin. You define your controllers in Kotlin, annotate them with @Operation and @Schema, and Spring Boot generates the same /v3/api-docs and Swagger UI endpoints. The integration story is nearly identical to the Java examples of integrating Swagger with Spring Boot applications shown earlier.

Q3. How do I hide internal endpoints from Swagger in a Spring Boot app?
Use @Hidden from io.swagger.v3.oas.annotations.Hidden on controllers or methods you don’t want exposed. Many examples of integrating Swagger with Spring Boot applications in enterprises use this to keep internal-only endpoints out of partner-facing documentation.

Q4. Is springfox still recommended for new Spring Boot projects?
No. For Spring Boot 3 and Jakarta namespaces, springdoc-openapi is the actively maintained option. Most 2024 tutorials and real examples of integrating Swagger with Spring Boot applications have moved away from springfox because it lags behind framework changes.

Q5. How big can an OpenAPI spec get before Swagger UI becomes slow?
Experience varies, but once you’re in the hundreds of endpoints, Swagger UI can feel heavy. That’s one reason why grouping APIs, versioning, and sometimes splitting large monoliths into multiple Spring Boot apps are common examples of integrating Swagger with Spring Boot applications at scale.

If you take nothing else away, remember this: the strongest examples of integrating Swagger with Spring Boot applications don’t treat Swagger as a pretty add-on. They treat the OpenAPI definition as a first-class artifact that guides design, testing, security, and communication across your entire engineering organization.