How do you adjust context-paths with Springdoc OpenAPI & GroupedOpenApi

Question

Background:

The task that we have is to move from two legacy APIs / services, to consolidate them and to introduce a newer v2 API - that all utilize the same underlying codebase.

My approach has been to utilize multiple @RestControllers, each with a class-level @RequestMapping. For ease of discussion, assume that the names / sub-paths are:

• /v1/legacy-api-1
• /v1/legacy-api-2
• /v2

I've created three GroupedOpenApi's that correspond to the different sub-paths, and everything looks great in Swagger-UI!

Previously, legacy-api-1 & legacy-api-2 have been available through an API manager at distinct endpoints and run as distinct services.

I'll focus on just legacy-api-1...

So, we'd like to update the API manager to load-balance between the existing versions of the legacy APIs as well as the new consolidated version. For example:

• {API_MANAGER_BASE_URL}/legacy-api-1
  • {OLD_LEGACY_API_1_URL}
  • {CONSOLIDATED_API_BASE_URL}/v1/legacy-api-1

This is totally feasible.

Where I run into problems is with Swagger-UI, and the generated OpenAPI definitions.

Ideally, I'd love to augment the OpenAPI definition's servers collection to be something similar to what exists in the API manager:

• {API_MANAGER_BASE_URL}/legacy-api-1
• {OLD_LEGACY_API_1_URL}
• {CONSOLIDATED_API_BASE_URL}/v1/legacy-api-1

which is totally doable via GroupedOpenApi.Builder.addOpenApiCustomiser.

However, all of the operations that are exposed for my API start with /v1/legacy-api-1/.

Example:

• GET /v1/legacy-api-1/document Retrieve document
• POST /v1/legacy-api-1/document Store document

Question:

How do I set a GroupedOpenApi-specific prefix to remove from the generated OpenAPI definitions / Swagger-UI?

Example (for prefix /v1/legacy-api-1):

• servers:
  • {API_MANAGER_BASE_URL}/legacy-api-1
  • {OLD_LEGACY_API_1_URL}
  • {CONSOLIDATED_API_BASE_URL}/v1/legacy-api-1 - i.e. the desired "Generated server url"
• operations:
  • GET /document Retrieve document
  • POST /document Store document

Or to word the question another way, how do I get a portion of the context-path to be moved from the operations over to the server element for a given GroupedOpenApi?

Answer 1

After a little more digging I found it in GroupedOpenApi.builder() (where basePath is something like /v1/legacy-api-1):

        .addOpenApiCustomiser(
            oApi -> {
              Paths paths = oApi.getPaths();
              // To avoid ConcurrentModificationException
              String[] keySet = paths.keySet().toArray(new String[0]);
              for (String key : keySet) {
                PathItem pathItem = paths.get(key);
                // Remove the basePath from the individual operation
                paths.put(key.replace(basePath, ""), pathItem);
                paths.remove(key);
              }

              Server server = oApi.getServers().get(0);
              // Add the basePath to the server entry
              server.setUrl(server.getUrl() + basePath);
            })