Mastering API Management with Swagger and Spring Boot: A Complete Guide

As a software developer, whether building low‑level applications, traditional web systems, or middleware servers, you need to expose APIs for external programs to interact with internal resources.

This article explains how to effectively manage application APIs, supporting automatic documentation generation, collaborative development, multiple API versions, and automated testing.

API Protocol Types

API protocols include:

REST API – the most common for web applications, using HTTP.

RPC API – based on frameworks like Dubbo, used for internal microservice communication.

WebSocket API – full‑duplex communication where client and server can push messages.

Managing APIs is a crucial part of the software lifecycle. To improve development efficiency, we use Apifox for API management.

OpenAPI (Swagger) Documentation

OpenAPI is a standard for describing RESTful APIs; Swagger is an implementation that defines how to describe interfaces and provides UI documentation. Spring projects typically use the Swagger2 library.

1. Swagger 2 Basic Configuration

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Then create a configuration class to enable Swagger documentation.

@Configuration
@EnableSwagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.su4j.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

Access the generated JSON at http://localhost:8080/v2/api-docs. The JSON can be imported directly into Apifox without using Swagger UI.

Swagger dependencies are provided by springfox-swagger2, which also supports YApi, RAML and other formats.

2. Swagger 2 Configuration Options

A more complete configuration example:

package com.su4j.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(false) // toggle Swagger
                .groupName("user-api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.puup.su4j.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("order-api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.order.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API Documentation Title")
                .description("Detailed description of the API")
                .version("1.0.0")
                .contact(new Contact("Developer", "https://developer.example.com", "[email protected]"))
                .build();
    }
}

3. Restrict Swagger to Development Environment

Add @Profile("dev") to the configuration class and set spring.profiles.active=dev in application-dev.properties. Alternatively, use

@ConditionalOnProperty(name="swagger.enabled", havingValue="true", matchIfMissing=true)

to enable Swagger only when the property is true.

4. Knife4j UI Enhancement

Knife4j improves the Swagger UI experience. Add the following Maven dependency:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

Managing API Versions

Versioning strategies include request headers, URL parameters, and path prefixes. Example using a request header:

@GetMapping("/users")
public List<User> getUsers(@RequestHeader(value = "X-API-Version", defaultValue = "v1") String apiVersion) {
    if ("v2".equals(apiVersion)) {
        return userService.getUpdatedUsers();
    }
    return userService.getUsers();
}

Clients can request /api/users?version=v1 or /api/users?version=v2, or use path‑based versioning such as /api/v1/users and /api/v2/users.