Swagger Codegen Maven插件生成含路径变量与请求参数代码异常

I ran into this exact issue before when dealing with Spring Web endpoints that share the same path but use different query parameters. Let's break down what's happening and how to fix it:

The Root Cause #

Your OpenAPI definition is using the {?login}/{?ids} syntax to embed query parameters directly in the path string. Older versions of Swagger Codegen misinterpret these as path variables instead of query parameters. So when it generates the stub code, it tries to pull ?login from the uriVariables map—which doesn't exist, hence the IllegalArgumentException.

Spring Web handles these endpoints fine because it looks at the full request (path + query params) to route, but this OpenAPI path syntax trips up the codegen tool.

Solutions #

1. Fix the OpenAPI Definition (Recommended) #

Rewrite your OpenAPI spec to explicitly define query parameters in the parameters array instead of embedding them in the path. This aligns with OpenAPI best practices and eliminates the codegen confusion.

Here's how your corrected spec should look (YAML example; adjust for JSON as needed):

paths:
  /start/{pathVar}/operators:
    # First endpoint: uses 'login' query param
    get:
      operationId: fetchOperatorsByLogin
      parameters:
        - name: pathVar
          in: path
          required: true
          schema:
            type: string
        - name: login
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success response
    # Second endpoint: uses 'ids' query param
    get:
      operationId: fetchOperatorsByIds
      parameters:
        - name: pathVar
          in: path
          required: true
          schema:
            type: string
        - name: ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Success response

• Ensure each operation has a unique operationId to avoid codegen conflicts.
• By defining in: query for the parameters, Swagger Codegen will generate methods that accept these as regular arguments, appending them to the URL as query params instead of treating them as path variables.

2. Customize the Swagger Codegen Template #

If you can't modify the OpenAPI spec, override the codegen template to fix the URL building logic.

For Java Spring stubs:

1. Grab the default api.mustache template from the Swagger Codegen repository.
2. Modify the URL construction section to separate path variables and query params, replacing the hardcoded path with a dynamic builder:

final Map<String, Object> uriVariables = new HashMap<String, Object>();
uriVariables.put("pathVar", pathVar);

// Build base path without query params
UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromPath("/start/{pathVar}/operators");

// Add query params dynamically
{{#queryParams}}
uriBuilder.queryParam("{{name}}", {{paramName}});
{{/queryParams}}

String path = uriBuilder.buildAndExpand(uriVariables).toUriString();

3. Configure your swagger-codegen-maven-plugin to use this custom template:

<plugin>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-codegen-maven-plugin</artifactId>
  <version>2.4.32</version> <!-- Use your current version -->
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/openapi.json</inputSpec>
        <language>spring</language>
        <templateDirectory>${project.basedir}/src/main/resources/swagger-templates</templateDirectory>
        <!-- Other existing configurations -->
      </configuration>
    </execution>
  </executions>
</plugin>

3. Switch to OpenAPI Generator #

Swagger Codegen has been largely superseded by OpenAPI Generator, which fixes many of these edge-case bugs. It handles duplicate paths with different query params correctly out of the box.

To use it in Maven:

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>7.2.0</version> <!-- Use the latest stable version -->
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/openapi.json</inputSpec>
        <generatorName>spring</generatorName>
        <!-- Other existing configurations -->
      </configuration>
    </execution>
  </executions>
</plugin>

The generated code will properly handle query params as method arguments, with no hardcoded path issues.

内容的提问来源于stack exchange，提问作者Duracel