swagger-maven-plugin 不会为单个请求映射生成 "paths" 元素

Question

我有一个简单的端点，我想用 swagger-maven-plugin 处理。生成的 swagger.conf 未反映单个 @Api 操作的正确 "paths:"。 api 的根是“/api”，我想将 GET 和 PUT 的端点添加到“/api/cluster”。相反，swagger.json 输出的 "paths:" 子句是“/api”。

这是 .java 来源，@Api(value="/api") 和 @RequestMapping(value="/api")在 class 上，以及带有 @RequestMapping(value = "/cluster") 的入口点：

ClusterManagerController.java:

    package com.vmturbo.clustermgr;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.*;

import javax.ws.rs.Path;
import java.io.OutputStream;
import java.util.Map;
import java.util.Set;

/**
 * REST endpoint for ClusterMgr, exposing APIs for component status, component configuration, node configuration.
 **/
@Component
@RestController
@Api(value = "/api", description = "Methods for managing the Ops Manager Cluster")
@RequestMapping(value="/api", produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.TEXT_PLAIN_VALUE})
public class ClusterMgrController {

    @Autowired
    private ClusterMgrService clusterMgrService;

    /**
     * Get a dump of the current Cluster Configuration
     *
     * @return a {@link com.vmturbo.clustermgr.ClusterMgrService.ClusterConfiguration} object containing known components,
     * components associated with each node, and property key/value maps for each component.
     */
    @ApiOperation(value = "Get a dump of the current cluster configuration")
    @RequestMapping(path = "/cluster",
            method = RequestMethod.GET)
    @ResponseBody
    public ClusterMgrService.ClusterConfiguration getClusterConfiguration() {
        return clusterMgrService.getClusterConfiguration();
    }

    /**
     * Replace the current Cluster Configuration with a new one.
     *
     * @return the new Cluster configuration, read back from the key/value store.
     */
    @ApiOperation(value = "Replace the current Cluster Configuration with a new one.")
    @RequestMapping(path = "/cluster",
            method = RequestMethod.PUT)
    @ResponseBody
    public ClusterMgrService.ClusterConfiguration setClusterConfiguration(
            @RequestBody ClusterMgrService.ClusterConfiguration newConfiguration) {
        return clusterMgrService.setClusterConfiguration(newConfiguration);
    }
}

而 swagger-maven-plugin 的 pom.xml 子句如下所示：

    <plugin>
        <groupId>com.github.kongchen</groupId>
        <artifactId>swagger-maven-plugin</artifactId>
        <version>3.1.1</version> <!-- TODO: move swagger version to top-level pom -->
        <configuration>
            <apiSources>
                <apiSource>
                    <springmvc>true</springmvc>
                    <schemes>http,https</schemes>
                    <basePath>/</basePath>
                    <locations>com.vmturbo.clustermgr.ClusterMgrController</locations>
                    <info>
                        <title>ClusterMgr REST API</title>
                        <version>v1</version>
                        <description>The API for configuration and control of a VMTurbo XL Ops Manager Cluster</description>
                    </info>
                    <swaggerDirectory>${swagger.conf.directory}</swaggerDirectory>
                </apiSource>
            </apiSources>
        </configuration>
        <executions>
            <execution>
                <phase>prepare-package</phase>
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

生成的 swagger.json 显示一个端点“/api”，带有 GET 和 PUT 子句。

{
  "swagger" : "2.0",
  "info" : {
    "description" : "The API for configuration and control of a VMTurbo XL Ops Manager Cluster",
    "version" : "v1",
    "title" : "ClusterMgr REST API"
  },
  "basePath" : "/",
  "tags" : [ {
    "name" : "api",
    "description" : "Methods for managing the Ops Manager Cluster"
  } ],
  "schemes" : [ "http", "https" ],
  "paths" : {
    "/api" : {
      "get" : {
        "tags" : [ "api" ],
        "summary" : "Get a dump of the current cluster configuration",
        "description" : "",
        "operationId" : "getClusterConfiguration",
        "produces" : [ "application/json", "text/plain" ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/ClusterConfiguration"
            }
          }
        }
      },
      "put" : {
        "tags" : [ "api" ],
        "summary" : "Replace the current Cluster Configuration with a new one.",
        "description" : "",
        "operationId" : "setClusterConfiguration",
        "produces" : [ "application/json", "text/plain" ],
        "parameters" : [ {
          "in" : "body",
          "name" : "body",
          "required" : false,
          "schema" : {
            "$ref" : "#/definitions/ClusterConfiguration"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/ClusterConfiguration"
            }
          }
        }
      }
    }
  },
  "definitions" : {
    "ClusterConfiguration" : {
      "type" : "object",
      "properties" : {
        "nodes" : {
          "type" : "object",
          "readOnly" : true,
          "additionalProperties" : {
            "$ref" : "#/definitions/ComponentPropertiesMap"
          }
        }
      }
    },
    "ComponentPropertiesMap" : {
      "type" : "object"
    }
  }
}

最后，我的 pom.xml swagger-maven-plugin 条目：

    <plugin>
        <groupId>com.github.kongchen</groupId>
        <artifactId>swagger-maven-plugin</artifactId>
        <version>3.1.1</version> <!-- TODO: move swagger version to top-level pom -->
        <configuration>
            <apiSources>
                <apiSource>
                    <springmvc>true</springmvc>
                    <schemes>http,https</schemes>
                    <basePath>/</basePath>
                    <locations>com.vmturbo.clustermgr.ClusterMgrController</locations>
                    <info>
                        <title>ClusterMgr REST API</title>
                        <version>v1</version>
                        <description>The API for configuration and control of a VMTurbo XL Ops Manager Cluster</description>
                    </info>
                    <swaggerDirectory>${swagger.conf.directory}</swaggerDirectory>
                </apiSource>
            </apiSources>
        </configuration>
        <executions>
            <execution>
                <phase>prepare-package</phase>
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

Answer 1

在尝试使用以下方法之前

 @RequestMapping(value = "/cluster", method = RequestMethod.GET)

swagger-maven-plugin 不会为单个请求映射生成 "paths" 元素

swagger-maven-plugin does not generate "paths" elements for individual request mappings

java

spring

maven

swagger

swagger-maven-plugin