Enum value not taken over

[JoopBL]

Swagger core version 1.5.12

The Java enumeration has the following code:

@XmlType(name = "PickPriority")
@XmlEnum
public enum PickPriority {

    @XmlEnumValue("1")
    VALUE_1("1"),

The following code is being generated:
{"name":"PickingPriority"},"enum":["VALUE_1",
The value() of the enumeration should be used.

[rwalkerands]

+1 ... sort of.

The parameter of @XmlEnumValue() should be used. Usually that is the same as the value().

See also https://groups.google.com/d/topic/swagger-swaggersocket/r3slMd2-fys/discussion

[JoopBL]

I found your discussion, it concerned issue #3.
In my example code I already use @XmlEnumValue. The value in SwaggerUI is VALUE_1 instead of 1.

Should I use my own ObjectMapper as described in your solution?

[rwalkerands]

In the case that JSON generated from the application (i.e., not the Swagger output) is coming from Jackson, does JSON output contain the correct value (1)? If not, you need a custom ObjectMapper that has the JaxbAnnotationModule registered.

[JoopBL]

The JSON output does not contain the correct value (1). I will have to look for an ObjectMapper example and see if this solves the problem.

[rwalkerands]

Using Jersey? Follow their instructions: https://jersey.java.net/documentation/latest/media.html#json.jackson

Sample class:

import javax.ws.rs.ext.ContextResolver;
import javax.ws.rs.ext.Provider;

import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;
import com.fasterxml.jackson.annotation.JsonInclude.Include;
import com.fasterxml.jackson.annotation.PropertyAccessor;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.module.jaxb.JaxbAnnotationModule;

/** Custom Jackson {@link ObjectMapper} provider for JSON deserialiation.
 * The customizations applied are:
 * (a) JAXB annotations are taken into account; (b) only non-null values
 * are included (c) only properties with getter methods are taken into account.
 * Note that despite (c), Jackson uses reflection to get values, rather
 * than calling getter methods. The difference is apparent for JAXB-generated
 * properties of List types, in which the getter method initializes the value
 * to an empty list, if the value is null.
 */
@Provider
public class ObjectMapperContextResolver
    implements ContextResolver<ObjectMapper> {

    /** Singleton ObjectMapper for JSON generation. It is OK for
     * this to be a singleton, as ObjectMappers are thread-safe. */
    private static final ObjectMapper OBJECTMAPPER = new ObjectMapper();

    static {
        JaxbAnnotationModule module = new JaxbAnnotationModule();
        OBJECTMAPPER.registerModule(module);
        OBJECTMAPPER.setSerializationInclusion(Include.NON_NULL);
//        OBJECTMAPPER.configure(SerializationFeature.WRITE_EMPTY_JSON_ARRAYS,
//                false);
        OBJECTMAPPER.setVisibility(PropertyAccessor.FIELD, Visibility.NONE);
    }

    /** Returns the singleton ObjectMapper instance to be used for
     * JSON deserialization.
     * @return The singleton ObjectMapper instance.
     */
    @Override
    public ObjectMapper getContext(final Class<?> type) {
        return OBJECTMAPPER;
    }

}

[JoopBL]

I wrote a custom ObjectMapper but the getContext is never called when refreshing from SwaggerUI. The constructor is called during startup. Any idea's?

`import javax.ws.rs.ext.ContextResolver;
import javax.ws.rs.ext.Provider;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.module.jaxb.JaxbAnnotationModule;

@Provider
public class EnumObjectMapperProvider implements ContextResolver {

private static final ObjectMapper OBJECTMAPPER = new ObjectMapper();

static {
	JaxbAnnotationModule module = new JaxbAnnotationModule();
	OBJECTMAPPER.registerModule(module);
	OBJECTMAPPER.configure(SerializationFeature.WRITE_ENUMS_USING_TO_STRING, true);
}

@Override
public ObjectMapper getContext(Class<?> type) {
	return OBJECTMAPPER;
}`

[rwalkerands]

The code I included in the previous comment was about getting your service itself (not Swagger) to produce the correct JSON. If you mean that the generated swagger.json is still wrong, then yes.

Here's a sample workaround.

The "problem" is the AbstractModelConverter constructor, which registers Swagger's own introspector, so that "our" JAXB introspector doesn't then get used to extract enum values.

So we override ModelResolver's _addEnumProps() method by creating an instance of an anonymous class. (Or, create your own subclass in a separate file if you prefer.)

package <put your package here>;

import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;

import com.fasterxml.jackson.databind.AnnotationIntrospector;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.module.jaxb.JaxbAnnotationIntrospector;
import com.fasterxml.jackson.module.jaxb.JaxbAnnotationModule;

import io.swagger.converter.ModelConverters;
import io.swagger.jackson.ModelResolver;
import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.models.properties.Property;
import io.swagger.models.properties.StringProperty;
import io.swagger.util.Json;

/** Class to bootstrap the configuration of the Swagger view of the API.
 */
public class SwaggerBootstrapper extends HttpServlet {

    /** Generated UID for serialization. */
    private static final long serialVersionUID = <put a long value here>L;

    /** Initialize the settings of the Swagger view of the API.
     */
    @Override
    public void init(final ServletConfig config) throws ServletException {
        super.init(config);

        // This makes Swagger honor JAXB annotations. Well,
        // not _all_ of them. It seems it doesn't respect
        // @XmlEnumValue.
        ObjectMapper mapper = Json.mapper();
        mapper.registerModule(new JaxbAnnotationModule());

        // Create a customized ModelResolver that uses the
        // JaxbAnnotationModule to get values of enumerated types.
        // Need to create an instance of an anonymous class that
        // overrides the _addEnumProps() method!
        final AnnotationIntrospector introspector =
                new JaxbAnnotationIntrospector(mapper.getTypeFactory());
        mapper.setAnnotationIntrospector(introspector);

        ModelResolver modelResolver = new ModelResolver(mapper) {
            @Override
            protected void _addEnumProps(final Class<?> propClass,
                    final Property property) {
                final boolean useIndex = _mapper.isEnabled(
                        SerializationFeature.WRITE_ENUMS_USING_INDEX);
                final boolean useToString = _mapper.isEnabled(
                        SerializationFeature.WRITE_ENUMS_USING_TO_STRING);

                @SuppressWarnings("unchecked")
                Class<Enum<?>> enumClass = (Class<Enum<?>>) propClass;
                for (Enum<?> en : enumClass.getEnumConstants()) {
                    String n;
                    if (useIndex) {
                        n = String.valueOf(en.ordinal());
                    } else if (useToString) {
                        n = en.toString();
                    } else {
                        // This is the original code, which gets the "first"
                        // introspector, which is Swagger's, not ours.
//                        n = _intr.findEnumValue(en);
                        // Instead, use the introspector we created above.
                        n = introspector.findEnumValue(en);
                    }
                    if (property instanceof StringProperty) {
                        StringProperty sp = (StringProperty) property;
                        sp._enum(n);
                    }
                }
            }
        };

        // Have Swagger use our custom ModelConverter when generating
        // swagger.json.
        ModelConverters.getInstance().addConverter(modelResolver);

        // Now define the top-level Swagger properties.
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setTitle("Vocabulary Registry API");
        beanConfig.setVersion("0.1.0");

        <set the reset of the beanConfig properties here>

        // Without scan=true, the top-level properties set in the previous
        // lines don't make their way into the generated swagger.json!
        beanConfig.setScan(true);
    }
}

Then use it in your web.xml:

  <!-- Swagger API. -->
  <servlet>
    <servlet-name>Jersey2Config</servlet-name>
    <servlet-class><put your package here>.SwaggerBootstrapper</servlet-class>
    <load-on-startup>2</load-on-startup>
  </servlet>

[JoopBL]

I have got this working. Thanks.
I had to go back jackson* dependencies version 2.6.7 due to error:
java.lang.NoSuchMethodError: com.fasterxml.jackson.databind.introspect.AnnotatedMember.getType()Lcom/fasterxml/jackson/databind/JavaType;
already mentioned here: FasterXML/jackson-module-jaxb-annotations#57

Now in swagger.json the output is OK. A minor issue in SwaggerUI remains:
<Name> (string) = ['1', '2', '3']stringEnum:"1", "2", "3"
Both a String and stringEnum are shown

[rwalkerands]

1. I'm using Jackson 2.4.4, so didn't have that problem.

2. I don't see any instance of "stringEnum". This seems to be the same as: Add @JsonProperty support for enum values springfox/springfox#1533
   Does indeed seem to be a swagger-ui thing. Try updating to the latest swagger-ui? I think that problem may go away.

[rwalkerands]

The swagger-ui issue was also reported directly here: swagger-api/swagger-ui#2656

Despite that issue being for swagger-ui 2.2.10, I am using 2.2.10 and not observing that problem.

[JoopBL]

The swagger-ui issue is solved in 2.2.10 indeed

[webron]

This is community cooperation at its best.

Is there any other issue that needs to be followed up on?

[rwalkerands]

Well, the original issue remains in the swagger-core code: it should use the values of the @XmlEnumValue() annotations when generating swagger.json. It may be that one has to do some configuration beforehand, e.g., what I do in the above init() method up to and including the line

mapper.setAnnotationIntrospector(introspector);

but, I believe, you shouldn't have to create a subclass of ModelResolver to get it to work.

What I've done is to provide a workaround that gives (me) what I believe should be the correct behaviour.

[rwalkerands]

I've been adding authentication to my API, and came across an issue with my SwaggerBootstrapper class given above, namely, the enums that are inside swagger-core aren't serialized correctly.

The enums inside swagger-core (e.g., io.swagger.models.auth.In) are specified using Jackson annotations, and my original SwaggerBootstrapper doesn't respect those Jackson annotations.

So you get in": "HEADER" instead of in": "header" in your swagger.json.

Please use this version instead:

package <put your package here>;

import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;

import com.fasterxml.jackson.databind.AnnotationIntrospector;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector;
import com.fasterxml.jackson.module.jaxb.JaxbAnnotationIntrospector;
import com.fasterxml.jackson.module.jaxb.JaxbAnnotationModule;

import io.swagger.converter.ModelConverters;
import io.swagger.jackson.ModelResolver;
import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.models.properties.Property;
import io.swagger.models.properties.StringProperty;
import io.swagger.util.Json;

/** Class to bootstrap the configuration of the Swagger view of the API.
 */
public class SwaggerBootstrapper extends HttpServlet {

    /** Generated UID for serialization. */
    private static final long serialVersionUID = <put a long value here>L;

    /** Initialize the settings of the Swagger view of the API.
     */
    @Override
    public void init(final ServletConfig config) throws ServletException {
        super.init(config);

        // This makes Swagger honor JAXB annotations. Well,
        // not _all_ of them. It seems it doesn't respect
        // @XmlEnumValue.
        ObjectMapper mapper = Json.mapper();
        mapper.registerModule(new JaxbAnnotationModule());

        // The problem is the constructor of Swagger's AbstractModelConverter
        // class, which "overrides" our introspector with Swagger's own.
        // At least, the "override" comes into play at a point we don't
        // want it to, i.e., when values of enums are extracted.

        // So, create a customized ModelResolver that uses the
        // JaxbAnnotationModule to get values of enumerated types.
        // Need to create an instance of an anonymous class that
        // overrides the _addEnumProps() method!
        // (Could also be done as a separate subclass, of course.)
        final AnnotationIntrospector jaxbIntrospector =
                new JaxbAnnotationIntrospector(mapper.getTypeFactory());
        // Also need Jackson's introspector, as it is used for
        // swagger-core's own enums (e.g., io.swagger.models.auth.In).
        final AnnotationIntrospector jacksonIntrospector =
                new JacksonAnnotationIntrospector();
        mapper.setAnnotationIntrospector(
                AnnotationIntrospector.pair(jacksonIntrospector,
                        jaxbIntrospector));

        ModelResolver modelResolver = new ModelResolver(mapper) {
            @Override
            protected void _addEnumProps(final Class<?> propClass,
                    final Property property) {
                final boolean useIndex = _mapper.isEnabled(
                        SerializationFeature.WRITE_ENUMS_USING_INDEX);
                final boolean useToString = _mapper.isEnabled(
                        SerializationFeature.WRITE_ENUMS_USING_TO_STRING);

                @SuppressWarnings("unchecked")
                Class<Enum<?>> enumClass = (Class<Enum<?>>) propClass;
                for (Enum<?> en : enumClass.getEnumConstants()) {
                    String n;
                    if (useIndex) {
                        n = String.valueOf(en.ordinal());
                    } else if (useToString) {
                        n = en.toString();
                    } else {
                        // This is the original code, which gets the "first"
                        // introspector, which is Swagger's, not ours.
//                        n = _intr.findEnumValue(en);
                        // Instead, use the introspector we created above.
                        n = jaxbIntrospector.findEnumValue(en);
                    }
                    if (property instanceof StringProperty) {
                        StringProperty sp = (StringProperty) property;
                        sp._enum(n);
                    }
                }
            }
        };

        // Have Swagger use our custom ModelConverter when generating
        // swagger.json.
        ModelConverters.getInstance().addConverter(modelResolver);

        // Now define the top-level Swagger properties.
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setTitle("Vocabulary Registry API");
        beanConfig.setVersion("0.1.0");

        <set the reset of the beanConfig properties here>

        // Without scan=true, the top-level properties set in the previous
        // lines don't make their way into the generated swagger.json!
        beanConfig.setScan(true);
    }
}