swagger-codegen: SwaggerCompatConverter throws NPE due to TRACE HTTP // no handling of duplicate nicknames

[jfiala]

With this api-doc (generated using the Basic Error Controller of the Swagger Spring-MVC project at https://github.com/springfox/springfox with com.mangofactory:swagger-springmvc-1.0.2)
SwaggerCompatConverter (Swagger-Codegen 2.1.2-M1) will throw an NPE:

com.wordnik.swagger.codegen.Codegen -i http://localhost:8080/api-docs -l java

java.lang.NullPointerException
at io.swagger.parser.SwaggerCompatConverter.convert(SwaggerCompatConverter.java:455)
at io.swagger.parser.SwaggerCompatConverter.read(SwaggerCompatConverter.java:111)
at io.swagger.parser.SwaggerParser.read(SwaggerParser.java:34)
at com.wordnik.swagger.codegen.Codegen.main(Codegen.java:93)

Full API-doc:

{
    "apiVersion": "1.0",
    "apis": [
        {
            "description": "error",
            "operations": [
                {
                    "method": "GET",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "HEAD",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "POST",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "PUT",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "PATCH",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "DELETE",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "OPTIONS",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }, {
                    "method": "TRACE",
                    "summary": "error",
                    "notes": "error",
                    "nickname": "error",
                    "produces": ["*/*"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "Map«string,object»"
                        }
                    ],
                    "deprecated": "false",
                    "type": "Map«string,object»"
                }
            ],
            "path": "/error"
        }, {
            "description": "errorHtml",
            "operations": [
                {
                    "method": "GET",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "HEAD",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "POST",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "PUT",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "PATCH",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "DELETE",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "OPTIONS",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }, {
                    "method": "TRACE",
                    "summary": "errorHtml",
                    "notes": "errorHtml",
                    "nickname": "errorHtml",
                    "produces": ["text/html"],
                    "consumes": ["application/json"],
                    "parameters": [],
                    "responseMessages": [
                        {
                            "code": 200,
                            "message": null,
                            "responseModel": "ModelAndView"
                        }
                    ],
                    "deprecated": "false",
                    "type": "ModelAndView"
                }
            ],
            "path": "/error"
        }
    ],
    "basePath": "/",
    "consumes": ["application/json"],
    "models": {
        "View": {
            "description": "",
            "id": "View",
            "properties": {
                "contentType": {
                    "required": false,
                    "type": "string"
                }
            }
        },
        "ModelAndView": {
            "description": "",
            "id": "ModelAndView",
            "properties": {
                "view": {
                    "required": false,
                    "type": "View"
                },
                "model": {
                    "required": false,
                    "type": "object"
                },
                "empty": {
                    "required": false,
                    "type": "boolean"
                },
                "modelMap": {
                    "required": false,
                    "type": "ModelMap"
                },
                "viewName": {
                    "required": false,
                    "type": "string"
                },
                "reference": {
                    "required": false,
                    "type": "boolean"
                }
            }
        },
        "ModelMap": {
            "description": "",
            "id": "ModelMap",
            "properties": {
                "empty": {
                    "required": false,
                    "type": "boolean"
                }
            }
        }
    },
    "produces": ["*/*", "text/html"],
    "resourcePath": "/error",
    "swaggerVersion": "1.2"
}

I tried to replace SwaggerCompatConverter, but right now it doesn't seem to be intended to replace the SwaggerCompatConverter easily, as it is parsed via "SwaggerParserExtension" and there is no reference to the class SwaggerCompatConverter in the whole swagger-codegen-project-2.1.2-M1 (to allow it to be edited):

SwaggerParser:

for(SwaggerParserExtension extension : parserExtensions) {
      try{
        output = extension.read(location, auths);
        if(output != null) {
          return output;
        }
      }

[webron]

Swagger doesn't support TRACE for REST calls in general. Other than that, that definition is malformed for using Maps with Swagger 1.2 (which is only supported in 2.0 and is represented differently) and it looks like none of the operations have any parameters which is especially odd for PUT, POST and PATCH requests.

[jfiala]

Thank you, I've posted it there (springfox/springfox#659).
There is a second issue with that API-doc:
After removing trace, the errorHtml()-method is duplicated within the ErrorApi itself, so it causes a compile error on ErrorApi.java:

  public ModelAndView errorHtml () throws ApiException {
   ...

    try {
      String response = apiInvoker.invokeAPI(basePath, path, "GET", queryParams, postBody, headerParams, formParams, contentType);
     ...
    }
  }


  public ModelAndView errorHtml () throws ApiException {
    Object postBody = null;

Is this behaviour erroneous due to Spring-MVC-Swagger or of Swagger-Codegen?

[webron]

That looks like a problem with the Swagger definition as well. They all have the same nickname value, and those have to be unique.

[fehguy]

We should handle duplicate nicknames in the codegen... maybe a new issue

[jfiala]

Maybe there should be an Exception (when duplicates are not allowed) or they could be handled somehow (by adding suffixes).

[jfiala]

The same error occurs with a Swagger 2.0 api-doc (generated also using Spring-Mvc-Swagger):

{
  "swagger": "2.0",
  "info": {
    "description": "Api Documentation",
    "version": "1.0",
    "title": "Api Documentation",
    "termsOfService": "urn:tos",
    "contact": {
      "name": "Contact Email"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0"
    }
  },
  "host": "localhost:8080",
  "basePath": "/",
  "tags": [
    {
      "name": "search-services"
    },
    {
      "name": "user-crud-responseentity"
    },
    {
      "name": "user-crud"
    },
    {
      "name": "basic-error-controller"
    }
  ],
  "paths": {
    "/error": {
      "get": {
        "tags": [
          "basic-error-controller"
        ],
        "summary": "error",
        "description": "error",
        "operationId": "error",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "basic-error-controller"
        ],
        "summary": "error",
        "description": "error",
        "operationId": "error",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "put": {
        "tags": [
          "basic-error-controller"
        ],
        "summary": "error",
        "description": "error",
        "operationId": "error",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "delete": {
        "tags": [
          "basic-error-controller"
        ],
        "summary": "error",
        "description": "error",
        "operationId": "error",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "options": {
        "tags": [
          "basic-error-controller"
        ],
        "summary": "error",
        "description": "error",
        "operationId": "error",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "patch": {
        "tags": [
          "basic-error-controller"
        ],
        "summary": "error",
        "description": "error",
        "operationId": "error",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object"
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/search": {
      "get": {
        "tags": [
          "search-services"
        ],
        "summary": "search for users by name-part",
        "description": "search for users",
        "operationId": "searchUsers",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/User"
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/user": {
      "get": {
        "tags": [
          "user-crud"
        ],
        "summary": "read User by ID",
        "description": "pass ID to read user",
        "operationId": "getUser",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "description": "id",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "user-crud"
        ],
        "summary": "create or update a user name by id",
        "description": "saveUser",
        "operationId": "saveUser",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "description": "id",
            "required": true,
            "type": "integer",
            "format": "int64"
          },
          {
            "name": "name",
            "in": "query",
            "description": "name",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/user_with_responseentity": {
      "get": {
        "tags": [
          "user-crud-responseentity"
        ],
        "summary": "getUserResponseEntity",
        "description": "getUserResponseEntity",
        "operationId": "getUserResponseEntity",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "description": "id",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          },
          "200": {
            "description": "OK",
            "schema": {
              "type": "object"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "500": {
            "description": "Unexpected Error"
          }
        }
      }
    }
  },
  "definitions": {
    "User": {
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "bytes": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "byte"
          }
        },
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "ID of the user"
        },
        "name": {
          "type": "string",
          "description": "Name of the user"
        },
        "state": {
          "type": "string",
          "enum": [
            "ACTIVE",
            "DISABLED"
          ]
        }
      },
      "description": "User object"
    },
    "View": {
      "properties": {
        "contentType": {
          "type": "string"
        }
      }
    },
    "ModelAndView": {
      "properties": {
        "empty": {
          "type": "boolean"
        },
        "model": {
          "type": "object"
        },
        "modelMap": {
          "type": "object",
          "additionalProperties": {
            "type": "object"
          }
        },
        "reference": {
          "type": "boolean"
        },
        "view": {
          "$ref": "#/definitions/View"
        },
        "viewName": {
          "type": "string"
        }
      }
    }
  }
}

 /**
   * error
   * error
   * @return Map<String, Object>
   */
  public Map<String, Object> error () throws ApiException {
...
 String response = apiInvoker.invokeAPI(basePath, path, "GET", queryParams, postBody, headerParams, formParams, contentType);
....

 /**
   * error
   * error
   * @return Map<String, Object>
   */
  public Map<String, Object> error () throws ApiException {
    String response = apiInvoker.invokeAPI(basePath, path, "PUT", queryParams, postBody, headerParams, formParams, contentType);

[jfiala]

The same error also occurs in PHP code generation:
PHP Fatal error: Cannot redeclare SwaggerPetstore\BasicerrorcontrollerApi::error() in J:\dev_php_new\confess-demo-client-codegen-2.1.2-M2\lib\BasicerrorcontrollerApi.php on line 89
PHP Stack trace:
PHP 1. {main}() J:\dev_php_new\confess-demo-client-codegen-2.1.2-M2\SwaggerPetstore.php:0

[dilipkrish]

Might not be a problem with Jax-RS services, but in spring a request mapping could represent more than one http method. For e.g. if the method doesnt specify a http method, any of the http verbs could be routed to this method.

This is a little different than how Jax-RS works. Now really from a swagger definition I know it is supposed to be unique, however, from a codegen perspective it will look weird if we manufacture unique nicknames like errorUsingPOST errorUsingGET etc. Thoughts?

[webron]

Actually, I don't think it would look that weird :) That's the whole idea being operationId in 2.0 - the consumer (in this case, codegen) need to work out the uniqueness of the given operation.

[dilipkrish]

Cant remember which property is visible to the end-user in the swagger UI. If I remember correctly it shows the summary on the far left of the operation. In which case generating that name should be fine. As long as we dont surface the unique identifier in the ui I'm 👍 with changing that behavior. Let me know

[webron]

The unique identifier is not visible to the user in the UI, it is used behind the scenes to control some mechanics (such as operation collapsing and so on).