Merge pull request #3740 from swagger-api/config-deterministic-sort

modules/swagger-core/src/main/java/io/swagger/v3/core/util/ObjectMapperFactory.java

@@ -35,7 +35,8 @@
 import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.links.Link;
 import io.swagger.v3.oas.models.links.LinkParameter;
-import io.swagger.v3.oas.models.media.DateSchema;import io.swagger.v3.oas.models.media.Encoding;
+import io.swagger.v3.oas.models.media.DateSchema;
+import io.swagger.v3.oas.models.media.Encoding;
 import io.swagger.v3.oas.models.media.EncodingProperty;
 import io.swagger.v3.oas.models.media.MediaType;
 import io.swagger.v3.oas.models.media.Schema;

modules/swagger-core/src/main/java/io/swagger/v3/core/util/ReflectionUtils.java

@@ -16,6 +16,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.Comparator;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Optional;
@@ -223,6 +224,9 @@ public static boolean isConstructorCompatible(Constructor<?> constructor) {
  * excluding <code>Object</code> class. If the field from child class hides the field from superclass,
  * the field from superclass won't be added to the result list.
  *
+ * The list is sorted by name to make the output of this method deterministic.
+ * See https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getFields--
+ *
  * @param cls is the processing class
  * @return list of Fields
  */
@@ -241,6 +245,10 @@ public static List<Field> getDeclaredFields(Class<?> cls) {
  fields.add(field);
  }
  }
+
+ // Make sure the order is deterministic
+ fields.sort(Comparator.comparing(Field::getName));
+
  return fields;
  }
 

modules/swagger-core/src/test/java/io/swagger/v3/core/serialization/ModelSerializerTest.java

@@ -367,4 +367,4 @@ public void testEnumWithNull() throws Exception {
  SerializationMatchers.assertEqualsToYaml(model, yaml);
 
  }
-}
+}

modules/swagger-core/src/test/java/io/swagger/v3/core/util/reflection/ReflectionUtilsTest.java

@@ -3,6 +3,7 @@
 import io.swagger.v3.core.util.ReflectionUtils;
 import io.swagger.v3.core.util.reflection.resources.Child;
 import io.swagger.v3.core.util.reflection.resources.IParent;
+import io.swagger.v3.core.util.reflection.resources.ObjectWithManyFields;
 import io.swagger.v3.core.util.reflection.resources.Parent;
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
@@ -11,10 +12,13 @@
 import org.testng.annotations.Test;
 
 import javax.ws.rs.Path;
+import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 import java.lang.reflect.Type;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
 
 import static org.testng.Assert.assertNull;
 
@@ -134,6 +138,14 @@ public void getDeclaredFieldsFromInterfaceTest() throws NoSuchMethodException {
  Assert.assertEquals(Collections.emptyList(), ReflectionUtils.getDeclaredFields(cls));
  }
 
+ @Test
+ public void declaredFieldsShouldBeSorted() {
+ final Class cls = ObjectWithManyFields.class;
+ final List<Field> declaredFields = ReflectionUtils.getDeclaredFields(cls);
+ Assert.assertEquals(4, declaredFields.size());
+ Assert.assertEquals(Arrays.asList("a", "b", "c", "d"), declaredFields.stream().map(Field::getName).collect(Collectors.toList()));
+ }
+
  @Test
  public void testFindMethodForNullClass() throws Exception {
  Method method = ReflectionUtilsTest.class.getMethod("testFindMethodForNullClass", (Class<?>[]) null);

modules/swagger-core/src/test/java/io/swagger/v3/core/util/reflection/resources/ObjectWithManyFields.java

@@ -0,0 +1,10 @@
+package io.swagger.v3.core.util.reflection.resources;
+
+public class ObjectWithManyFields {
+
+ public String a;
+ public boolean d;
+ public Integer c;
+ public Object b;
+
+}

modules/swagger-gradle-plugin/README.md

@@ -64,6 +64,7 @@ Parameter | Description | Required | Default
 `resourcePackages`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
 `resourceClasses`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
 `prettyPrint`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`TRUE`
+`sortOutput`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`FALSE`
 `openApiFile`|openapi file to be merged with resolved specification, equivalent to [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties) openAPI|false|
 `filterClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
 `readerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
@@ -95,3 +96,6 @@ info:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
 ```
+
+Since version 2.1.6, `sortOutput` parameter is available, allowing to sort object properties and map keys alphabetically.
+Since version 2.1.6, `objectMapperProcessorClass` allows to configure also the ObjectMapper instance used to serialize the resolved OpenAPI

modules/swagger-gradle-plugin/src/main/java/io/swagger/v3/plugins/gradle/tasks/ResolveTask.java

@@ -66,6 +66,8 @@ public enum Format {JSON, YAML, JSONANDYAML};
  private LinkedHashSet<String> modelConverterClasses;
  private String objectMapperProcessorClass;
 
+ private Boolean sortOutput = Boolean.FALSE;
+
  private String contextId;
 
  @Input
@@ -294,6 +296,17 @@ public void setEncoding(String resourceClasses) {
  this.encoding = encoding;
  }
 
+ @Input
+ @Optional
+ public Boolean getSortOutput() {
+ return sortOutput;
+ }
+
+ public void setSortOutput(Boolean sortOutput) {
+ this.sortOutput = sortOutput;
+ }
+
+
  @TaskAction
  public void resolve() throws GradleException {
  if (skip) {
@@ -390,6 +403,9 @@ public void resolve() throws GradleException {
  method=swaggerLoaderClass.getDeclaredMethod("setPrettyPrint", Boolean.class);
  method.invoke(swaggerLoader, prettyPrint);
 
+ method=swaggerLoaderClass.getDeclaredMethod("setSortOutput", Boolean.class);
+ method.invoke(swaggerLoader, sortOutput);
+
  method=swaggerLoaderClass.getDeclaredMethod("setReadAllResources", Boolean.class);
  method.invoke(swaggerLoader, readAllResources);
 

modules/swagger-integration/src/main/java/io/swagger/v3/oas/integration/GenericOpenApiContext.java

@@ -1,16 +1,29 @@
 package io.swagger.v3.oas.integration;
 
+import com.fasterxml.jackson.annotation.JsonAnyGetter;
+import com.fasterxml.jackson.annotation.JsonAnySetter;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.databind.MapperFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import io.swagger.v3.core.converter.ModelConverter;
 import io.swagger.v3.core.converter.ModelConverters;
 import io.swagger.v3.core.jackson.ModelResolver;
+import io.swagger.v3.core.jackson.PathsSerializer;
+import io.swagger.v3.core.util.Json;
+import io.swagger.v3.core.util.Yaml;
 import io.swagger.v3.oas.integration.api.ObjectMapperProcessor;
 import io.swagger.v3.oas.integration.api.OpenAPIConfiguration;
 import io.swagger.v3.oas.integration.api.OpenApiConfigurationLoader;
 import io.swagger.v3.oas.integration.api.OpenApiContext;
 import io.swagger.v3.oas.integration.api.OpenApiReader;
 import io.swagger.v3.oas.integration.api.OpenApiScanner;
 import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.Paths;
+import io.swagger.v3.oas.models.media.Schema;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.tuple.ImmutablePair;
 import org.slf4j.Logger;
@@ -43,6 +56,9 @@ public class GenericOpenApiContext<T extends GenericOpenApiContext> implements O
  private ObjectMapperProcessor objectMapperProcessor;
  private Set<ModelConverter> modelConverters;
 
+ private ObjectMapper outputJsonMapper;
+ private ObjectMapper outputYamlMapper;
+
  private ConcurrentHashMap<String, Cache> cache = new ConcurrentHashMap<>();
 
  // 0 doesn't cache
@@ -210,6 +226,52 @@ public final T modelConverters(Set<ModelConverter> modelConverters) {
  return (T) this;
  }
 
+ /**
+ * @since 2.1.6
+ */
+ public ObjectMapper getOutputJsonMapper() {
+ return outputJsonMapper;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ @Override
+ public void setOutputJsonMapper(ObjectMapper outputJsonMapper) {
+ this.outputJsonMapper = outputJsonMapper;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ public final T outputJsonMapper(ObjectMapper outputJsonMapper) {
+ this.outputJsonMapper = outputJsonMapper;
+ return (T) this;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ public ObjectMapper getOutputYamlMapper() {
+ return outputYamlMapper;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ @Override
+ public void setOutputYamlMapper(ObjectMapper outputYamlMapper) {
+ this.outputYamlMapper = outputYamlMapper;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ public final T outputYamlMapper(ObjectMapper outputYamlMapper) {
+ this.outputYamlMapper = outputYamlMapper;
+ return (T) this;
+ }
+
 
  protected void register() {
  OpenApiContextLocator.getInstance().putOpenApiContext(id, this);
@@ -363,16 +425,36 @@ public T init() throws OpenApiConfigurationException {
  if (modelConverters == null || modelConverters.isEmpty()) {
  modelConverters = buildModelConverters(ContextUtils.deepCopy(openApiConfiguration));
  }
+ if (outputJsonMapper == null) {
+ outputJsonMapper = Json.mapper().copy();
+ }
+ if (outputYamlMapper == null) {
+ outputYamlMapper = Yaml.mapper().copy();
+ }
+ if (openApiConfiguration.isSortOutput() != null && openApiConfiguration.isSortOutput()) {
+ outputJsonMapper.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS, true);
+ outputJsonMapper.configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, true);
+ outputYamlMapper.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS, true);
+ outputYamlMapper.configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, true);
+ outputJsonMapper.addMixIn(OpenAPI.class, SortedOpenAPIMixin.class);
+ outputJsonMapper.addMixIn(Schema.class, SortedSchemaMixin.class);
+ outputYamlMapper.addMixIn(OpenAPI.class, SortedOpenAPIMixin.class);
+ outputYamlMapper.addMixIn(Schema.class, SortedSchemaMixin.class);
+ }
  } catch (Exception e) {
  LOGGER.error("error initializing context: " + e.getMessage(), e);
  throw new OpenApiConfigurationException("error initializing context: " + e.getMessage(), e);
  }
 
+
  try {
  if (objectMapperProcessor != null) {
  ObjectMapper mapper = IntegrationObjectMapperFactory.createJson();
  objectMapperProcessor.processJsonObjectMapper(mapper);
  ModelConverters.getInstance().addConverter(new ModelResolver(mapper));
+
+ objectMapperProcessor.processOutputJsonObjectMapper(outputJsonMapper);
+ objectMapperProcessor.processOutputYamlObjectMapper(outputYamlMapper);
  }
  } catch (Exception e) {
  LOGGER.error("error configuring objectMapper: " + e.getMessage(), e);
@@ -442,6 +524,9 @@ private OpenAPIConfiguration mergeParentConfiguration(OpenAPIConfiguration confi
  if (merged.isPrettyPrint() == null) {
  merged.setPrettyPrint(parentConfig.isPrettyPrint());
  }
+ if (merged.isSortOutput() == null) {
+ merged.setSortOutput(parentConfig.isSortOutput());
+ }
  if (merged.isReadAllResources() == null) {
  merged.setReadAllResources(parentConfig.isReadAllResources());
  }
@@ -493,4 +578,36 @@ boolean isStale(long cacheTTL) {
  }
  }
 
+ @JsonPropertyOrder(value = {"openapi", "info", "externalDocs", "servers", "security", "tags", "paths", "components"}, alphabetic = true)
+ static abstract class SortedOpenAPIMixin {
+
+ @JsonAnyGetter
+ @JsonPropertyOrder(alphabetic = true)
+ public abstract Map<String, Object> getExtensions();
+
+ @JsonAnySetter
+ public abstract void addExtension(String name, Object value);
+
+ @JsonSerialize(using = PathsSerializer.class)
+ public abstract Paths getPaths();
+ }
+
+ @JsonPropertyOrder(value = {"type", "format"}, alphabetic = true)
+ static abstract class SortedSchemaMixin {
+
+ @JsonAnyGetter
+ @JsonPropertyOrder(alphabetic = true)
+ public abstract Map<String, Object> getExtensions();
+
+ @JsonAnySetter
+ public abstract void addExtension(String name, Object value);
+
+ @JsonIgnore
+ public abstract boolean getExampleSetFlag();
+
+ @JsonInclude(JsonInclude.Include.CUSTOM)
+ public abstract Object getExample();
+
+ }
+
 }

modules/swagger-integration/src/main/java/io/swagger/v3/oas/integration/SwaggerConfiguration.java

@@ -30,6 +30,8 @@ public class SwaggerConfiguration implements OpenAPIConfiguration {
  private Set<String> modelConverterClasses;
  private String objectMapperProcessorClass;
 
+ private Boolean sortOutput;
+
  public Long getCacheTTL() {
  return cacheTTL;
  }
@@ -231,4 +233,27 @@ public SwaggerConfiguration modelConverterClasses(Set<String> modelConverterClas
  this.modelConverterClasses = modelConverterClasses;
  return this;
  }
+
+ /**
+ * @since 2.1.6
+ */
+ @Override
+ public Boolean isSortOutput() {
+ return sortOutput;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ public void setSortOutput(Boolean sortOutput) {
+ this.sortOutput = sortOutput;
+ }
+
+ /**
+ * @since 2.1.6
+ */
+ public SwaggerConfiguration sortOutput(Boolean sortOutput) {
+ setSortOutput(sortOutput);
+ return this;
+ }
 }

modules/swagger-integration/src/main/java/io/swagger/v3/oas/integration/api/ObjectMapperProcessor.java

@@ -7,12 +7,24 @@
  */
 public interface ObjectMapperProcessor {
 
- void processJsonObjectMapper(ObjectMapper mapper);
+ default void processJsonObjectMapper(ObjectMapper mapper) {};
 
  /**
  * @deprecated since 2.0.7, as no-op
  *
  */
  @Deprecated
- void processYamlObjectMapper(ObjectMapper mapper);
+ default void processYamlObjectMapper(ObjectMapper mapper) {}
+
+ /**
+ * @since 2.1.6
+ */
+ default void processOutputJsonObjectMapper(ObjectMapper mapper) {}
+
+ /**
+ * @since 2.1.6
+ */
+ default void processOutputYamlObjectMapper(ObjectMapper mapper) {
+ processOutputJsonObjectMapper(mapper);
+ }
 }

modules/swagger-integration/src/main/java/io/swagger/v3/oas/integration/api/OpenAPIConfiguration.java

@@ -39,4 +39,9 @@ public interface OpenAPIConfiguration {
  */
  public Set<String> getModelConverterClasses();
 
+ /**
+ * @since 2.1.6
+ */
+ Boolean isSortOutput();
+
 }