Introduction

When Springfox Swagger 2 shows the wrong base path, the root problem is usually not Swagger UI itself but how Springfox builds documented paths from your application mappings. In most cases, the fix is either a simple pathMapping on the Docket or a custom path provider when the service sits behind a proxy or gateway.

Use pathMapping for a Simple Prefix

If your API is served under a stable prefix such as /api, the simplest fix is Docket.pathMapping(...). This tells Springfox to prepend that prefix when it generates the documented operation paths.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import springfox.documentation.builders.PathSelectors;
4import springfox.documentation.builders.RequestHandlerSelectors;
5import springfox.documentation.spi.DocumentationType;
6import springfox.documentation.spring.web.plugins.Docket;
7
8@Configuration
9public class SwaggerConfig {
10
11    @Bean
12    public Docket api() {
13        return new Docket(DocumentationType.SWAGGER_2)
14                .select()
15                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
16                .paths(PathSelectors.any())
17                .build()
18                .pathMapping("/api");
19    }
20}

With that configuration, an endpoint mapped internally as /users is documented as /api/users. That is usually the right answer when the application really does live under a local servlet prefix.

Use a Custom PathProvider Behind a Gateway

If the externally visible route is different because of a reverse proxy or API gateway, a hard-coded pathMapping may not be enough. In that case, overriding the base path through a custom PathProvider is more precise.

1import javax.servlet.ServletContext;
2import org.springframework.context.annotation.Bean;
3import org.springframework.context.annotation.Configuration;
4import springfox.documentation.builders.PathSelectors;
5import springfox.documentation.builders.RequestHandlerSelectors;
6import springfox.documentation.spi.DocumentationType;
7import springfox.documentation.spring.web.paths.RelativePathProvider;
8import springfox.documentation.spring.web.plugins.Docket;
9
10@Configuration
11public class SwaggerConfig {
12
13    @Bean
14    public Docket api(ServletContext servletContext) {
15        return new Docket(DocumentationType.SWAGGER_2)
16                .select()
17                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
18                .paths(PathSelectors.any())
19                .build()
20                .pathProvider(new RelativePathProvider(servletContext) {
21                    @Override
22                    public String getApplicationBasePath() {
23                        return "/gateway/orders-service";
24                    }
25                });
26    }
27}

This is useful when the app's internal controller mappings are correct, but the route exposed to clients includes extra proxy prefixes that Springfox cannot infer on its own.

Keep Documentation Routing Separate from App Routing

If your whole application already runs under a context path, configure that at the Spring Boot level first:

server.servlet.context-path=/api

Springfox should then reflect the actual route structure more naturally. pathMapping is best used when you need a documentation prefix, not as a substitute for fixing the real application routing.

Another practical point is environment drift. A hard-coded gateway prefix might work in development and break in staging if the ingress path differs. When paths vary by environment, consider externalized configuration or proper forwarded-header handling instead of scattering constants through Swagger config.

It is also worth separating three different concerns that are often mixed together: controller mappings, application context path, and externally published gateway path. When those are treated as one setting, teams end up changing Springfox output instead of fixing the route that clients actually use. A short review of the deployment topology usually prevents that confusion.

If you are operating behind a load balancer or ingress controller, inspect the generated Swagger JSON directly instead of only looking at Swagger UI. The JSON output reveals whether Springfox is building incorrect paths at generation time or whether the browser is reaching the docs through a different prefix than the application expects. That distinction makes debugging much faster.

Common Pitfalls

• Using pathMapping to paper over a reverse-proxy routing problem.
• Hard-coding a prefix that differs between environments.
• Forgetting that controller @RequestMapping values still shape the final path.
• Changing documentation paths without changing the real route seen by clients.
• Treating Springfox configuration as the only place where path issues can be fixed.

Summary

• Use Docket.pathMapping(...) when you need a simple fixed base prefix.
• Use a custom PathProvider when proxy or gateway routing changes the external base path.
• Keep Spring Boot context-path settings separate from documentation-only adjustments.
• Fix infrastructure routing issues in the infrastructure layer when possible.
• In Springfox, base-path problems usually come down to pathMapping or pathProvider.