This is by design. I know the swagger ui and the swagger editor don't render this correctly. This might be a problem with the code gen too.

By "by design", do you mean the JSON spec file meets the swagger spec for this type of case?

"By design" meaning this is the best way to describe this in the spec such that its semantically equivalent to the json that is serialized over the wire.

Okay.

So does there need to be a change made in springfox to get the swagger ui to display all of the allowable options correctly? Or does there only need to be a change made in swagger ui?

If no change is needed in springfox then obviously there is a defect in the code gen. So I guess it just comes down to whether springfox needs an update or not. 😄

I would venture to say that swagger-ui doesn't render correctly.

I would also venture out and say after some investigation right now, that there is a feature that springfox doesn't support.... yet

Given

  @RequestMapping(value = "/enums", method = RequestMethod.GET, produces = { MediaTypes.HAL_JSON_VALUE })
  @ResponseBody
  public HttpEntity<List<AnEnum>> getEnums() {
    throw new UnsupportedOperationException();
  }

Generates this:

{
    "/upload/enums": {
        "get": {
            "consumes": [
                "application/json"
            ],
            "operationId": "getEnumsUsingGET",
            "produces": [
                "application/hal+json"
            ],
            "responses": {
                "200": {
                    "description": "OK",
                    "schema": {
                        "items": {
                            "type": "string"
                           // SHOULD ALSO GENERATE this
                           // "enum": [
                           //     "ONE",
                           //   "TWO"
                           // ]
                        },
                        "type": "array"
                    }
                },
                "401": {
                    "description": "Unauthorized"
                },
                "403": {
                    "description": "Forbidden"
                },
                "404": {
                    "description": "Not Found"
                }
            },
            "summary": "getEnums",
            "tags": [
                "file-upload-controller"
            ]
        }
    }
}

Thanks for persisting 🤘 I've made it a feature request

Cool. I'll post a JSON snippet tomorrow that shows what I'm currently getting. Thanks.

Here is what the Java looks like that I'm dealing with:

@ApiModelProperty(value="a list of values", allowableValues="foo,bar,baz", required=false)
public void setValues(List<String> values) {
    this.values = values;
}

And here is the resulting part from the swagger spec file:

"values": {
    "type": "array",
    "description":  "a list of values",
    "items": {
        "type": "string",
        "enum": [
            "foo",
            "bar",
            "baz"
        ]
    }
}

As noted, the swagger ui is not showing the available options (foo, bar, baz).

Is this JSON style correct, or should it be defined differently for this case? The answer to that will lead me to look more into submitting issues against swagger-ui and swagger-codegen.

Thanks!

@smwurster Im assuming that by this 👇

And here is the resulting part from the swagger spec file:

you mean that this is what you expect to be rendered

you mean that this is what you expect to be rendered

No, that's what I am getting. Is that to be expected? That is, is it valid?

To compare, this is what you get when you just have a single String as the type:

"someValue": {
    "type": "string",
    "description": "asdf",
    "enum": [
        "foo",
        "bar"
    ]
}

For this case, swagger-ui will show the options and the code generator never complains.

Ok cool .. the problem isn't as bad as I thought then. Just to restate the problem on springfox's end. When we have a parameter (not model property) that is a list of enums the rendered output is missing the enum under the items property, like you have above.

So is the items property supposed to be there for model classes that declare allowable values but only support one at a time?

No thats not what I meant...

When you have a List<SomeEnum> as a property, it seems like its working fine.

e.g. this totally seems to be working

requestMapping(SomeModel model) 

class SomeModel {
   List<SomeEnum> enums;
}

e.g. this totally seems to be working

but this does not work as expected.

requestMapping(List<SomeEnum> enums) 

In my case, I have this:

@ApiOperation(...)
void requestMapping(SomeModel model);

class SomeModel {
    @ApiModelProperty(allowableValues="Foo,Bar,Baz")
    List<String> getThings();
}

This is not working as I expect. The JSON spec file looks different for this compared to this model:

class SomeModel {
    @ApiModelProperty(allowableValues="Foo,Bar,Baz")
    String getThing();
}

The second option works as I expect in the UI, and the Java code is generated correctly. The first option does not display correctly in the UI, and the Java code fails to generate.

So where do the defects reside: springfox, swagger-ui, and/or swagger-codegen?

From what I can tell, this is what the JSON should look like for my case:

"values": {
    "type": "array",
    "description": "a list of values",
    "items": {
        "type": "string"
    },
    "enum": [
        "foo",
        "bar",
        "baz"
    ]
}

Note that the enums are at the top-level in the values element, while the items element only contains the type. When the JSON is formatted this way the swagger-ui online editor will show all of the allowable options correctly. Likewise, the swagger-codegen will not fail to generate Java code, and will properly define this entry as a list (which it is in Java).

Ended up reverting the fix as I realized the swagger models do not support enums in array types :(

My comment from November 9th 2015 shows what the output is supposed to look like. As I noted in that comment, the swagger-ui online editor will accept that (or at least it did at the time) and will show all of the allowable values correctly.

@smwurster was a lil' confused with all the different things that the enums could surface in. This is now fixed for any parameter (except for body parameters which does not support enums)

Cool. I'm looking forward to the next release.

This is still broken in 2.4.0 (sorry, just checking this now). There is no change to the generated JSON between 2.2.2 and 2.4.0 for this scenario.

@smwurster perhaps create a new issue? It gets real confusing after a long thread what the original issue was?

Will do.

Submitted #1329