Swagger adding description to enums

Question

I have a class that looks like this:

public class Rule {

    private RuleType type; //enum
    private String value;
}

The enum is:

public enum RuleType {
    TYPE_A, TYPE_B, TYPE_C;
}

Now each rule type the values are different. TYPE_A requires a number 1 through 10, TYPE_B is true or false, and TYPE_C is a string. I am trying to add swagger annotations to the enum so that the documentation can show this, something like this:

public enum RuleType {
    @ApiModelProperty(value = "1 - 10")
    TYPE_A, 
    @ApiModelProperty(value = "True or False")
    TYPE_B, 
    @ApiModelProperty(value = "String")
    TYPE_C;
}

But this doesn't work. The swagger produced just ignores the properties on the enums. Is there a way to create documentation like this?

How can an enum value itself have multiple values? If the enum is `TYPE_A`, it would always be `TYPE_A` itself right? If it can have multiple values, it should be of a different data type and not an enum. For eg, if `TYPE_B` can be true or false, you should be using a boolean instead right? I believe you need to change your class design. — Madhu Bhat, Jul 31 '18 at 15:47
OpenAPI Specification (and, by extension, Swagger tools) does not support descriptions for individual enum values (here's a related [feature request](https://github.com/OAI/OpenAPI-Specification/issues/348)). You'll probably need to specify these descriptions in the annotations for `RuleType`. — Helen, Jul 31 '18 at 15:53
Any update on this? I use SpringDoc 1.4.3 and am facing the same issue. — Michael Kemmerzell, Jul 16 '20 at 13:14
There is a github project that apparently solves this: https://github.com/hoereth/springfox-enum-plugin. — pringi, Jul 21 '22 at 18:02

score 0 · Answer 1 · edited Aug 05 '23 at 01:33

You cannot do this as you like. But there is another simple solution which you want.

public class Rule {

    @ApiModelProperty(value = 
            "TYPE_A must be 1 - 10\n" +
            "TYPE_B must be True or False\n" +
            "TYPE_C must be String")
    private RuleType type; //enum
    private String value;
}

You can see final result of this code with this link: https://i.stack.imgur.com/pMA6N.png

Swagger adding description to enums

1 Answers1