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

Question

I have a simple endpoint I would like to process with the swagger-maven-plugin. The resulting swagger.conf doesn't reflect the correct "paths:" for the individual @ApiOperations. The root of the api is "/api", and I want to add endpoints for GET and PUT to "/api/cluster". Instead, the "paths:" clause of the swagger.json output is "/api".

Here is the .java source, with @Api(value="/api") and @RequestMapping(value="/api") on the class, and entry points with @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);
    }
}

And the pom.xml clause for the swagger-maven-plugin looks like:

    <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>

The generated swagger.json shows one endpoint, "/api", with the GET and PUT clauses.

{
  "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"
    }
  }
}

Finally, my pom.xml entry for the 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>

Unblock

Could you post your <dependencies> section also? – Uncloak

Have you tried @Path( "/cluster" ) and @GET instead of @RequestMapping(path = "/cluster", method = RequestMethod.PUT) – Afrit

I think you are mixing things up here and that may be the cause of your problem. Your are using springs Requestmapping once with "value", once with "path" parameters. Spring web 4 doesn't know the "path" annotation parameter at all. So what exact version of spring are you using? Try using @RequestMapping(value = "/cluster", method = RequestMethod.GET) (i.e "value" instead of "path" annotation parameter) – Montiel

Answer 1

Before the method try using the following

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

Berton

Exactly right...thanks. And thanks to @Montiel as well for the same answer. – Unblock