Add support for adding Markdown descriptions to models in OpenAPI spec

gemma-web/src/main/java/ubic/gemma/web/services/rest/SearchWebService.java

@@ -29,7 +29,6 @@
 import ubic.gemma.model.genome.sequenceAnalysis.BioSequenceValueObject;
 import ubic.gemma.persistence.service.expression.arrayDesign.ArrayDesignService;
 import ubic.gemma.persistence.service.genome.taxon.TaxonService;
-import ubic.gemma.web.services.rest.swagger.resolvers.SearchResultTypeAllowableValuesModelResolver;
 import ubic.gemma.web.services.rest.util.ResponseDataObject;
 import ubic.gemma.web.services.rest.util.args.LimitArg;
 import ubic.gemma.web.services.rest.util.args.PlatformArg;
@@ -75,7 +74,7 @@ public class SearchWebService {
     /**
      * Search everything subject to taxon and platform constraints.
      * <p>
-     * Naming the schema in for the result types is necessary so that it can be resolved in {@link SearchResultTypeAllowableValuesModelResolver}.
+     * Naming the schema in for the result types is necessary so that it can be resolved in {@link ubic.gemma.web.services.rest.swagger.resolver.CustomModelResolver}.
      */
     @GET
     @Produces(MediaType.APPLICATION_JSON_VALUE)

gemma-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolver.java

@@ -0,0 +1,116 @@
+package ubic.gemma.web.services.rest.swagger.resolver;
+
+import com.fasterxml.jackson.databind.JavaType;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.introspect.Annotated;
+import io.swagger.v3.core.converter.AnnotatedType;
+import io.swagger.v3.core.converter.ModelConverter;
+import io.swagger.v3.core.converter.ModelConverterContext;
+import io.swagger.v3.core.converter.ModelConverters;
+import io.swagger.v3.core.jackson.ModelResolver;
+import io.swagger.v3.core.util.Json;
+import io.swagger.v3.oas.models.media.Schema;
+import lombok.Value;
+import lombok.extern.apachecommons.CommonsLog;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.stereotype.Component;
+import org.springframework.util.StreamUtils;
+import ubic.gemma.core.search.SearchService;
+import ubic.gemma.web.services.rest.SearchWebService;
+import ubic.gemma.web.services.rest.util.args.Arg;
+import ubic.gemma.web.services.rest.util.args.LimitArg;
+import ubic.gemma.web.services.rest.util.args.PlatformArg;
+import ubic.gemma.web.services.rest.util.args.TaxonArg;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Modifier;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * Resolve {@link Arg} parameters' schema.
+ *
+ * This should always be added last with {@link ModelConverters#addConverter(ModelConverter)} to take priority as it
+ * addresses a glitch in the original {@link ModelResolver}.
+ *
+ * @author poirigui
+ */
+@Component
+@CommonsLog
+@SuppressWarnings("DefaultAnnotationParam")
+public class CustomModelResolver extends ModelResolver {
+
+    private final SearchService searchService;
+
+    private final Map<String, String> descriptionsCache = new HashMap<String, String>();
+
+    @Autowired
+    public CustomModelResolver( @Qualifier("swaggerObjectMapper") ObjectMapper objectMapper, SearchService searchService ) {
+        super( objectMapper );
+        this.searchService = searchService;
+    }
+
+    @Override
+    public Schema resolve( AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain ) {
+        JavaType t = Json.mapper().constructType( type.getType() );
+        if ( Arg.class.isAssignableFrom( t.getRawClass() ) ) {
+            // I'm suspecting there's a bug in Swagger that causes request parameters annotations to shadow the
+            // definitions in the class's Schema annotation
+            Schema resolvedSchema = super.resolve( new AnnotatedType( ( t.getRawClass() ) ), context, chain );
+            // There's a bug with abstract class such as TaxonArg and GeneArg that result in the schema containing 'type'
+            // and 'properties' fields instead of solely emiting the oneOf
+            if ( Modifier.isAbstract( t.getRawClass().getModifiers() ) ) {
+                return resolvedSchema.type( null ).properties( null );
+            } else {
+                return resolvedSchema;
+            }
+        } else {
+            try {
+                return super.resolve( type, context, chain );
+            } finally {
+                descriptionsCache.clear();
+            }
+        }
+    }
+
+    /**
+     * Resolves allowed values for the {@link ubic.gemma.web.services.rest.SearchWebService#search(String, TaxonArg, PlatformArg, List, LimitArg)}
+     * resultTypes argument.
+     *
+     * This ensures that the OpenAPI specification exposes all supported search result types in the {@link SearchService} as
+     * allowable values.
+     */
+    @Override
+    protected List<String> resolveAllowableValues( Annotated a, Annotation[] annotations, io.swagger.v3.oas.annotations.media.Schema schema ) {
+        if ( schema != null && schema.name().equals( SearchWebService.RESULT_TYPES_SCHEMA_NAME ) ) {
+            return searchService.getSupportedResultTypes().stream().map( Class::getName ).collect( Collectors.toList() );
+        }
+        return super.resolveAllowableValues( a, annotations, schema );
+    }
+
+
+    @Override
+    protected String resolveDescription( Annotated a, Annotation[] annotations, io.swagger.v3.oas.annotations.media.Schema schema ) {
+        if ( descriptionsCache.containsKey( a.getName() ) ) {
+            log.info( String.format( "Got description from cache for %s%n", a ) );
+            return descriptionsCache.get( a.getName() );
+        }
+        ClassPathResource cpr = new ClassPathResource( "restapidocs/models/" + a.getName() + ".md" );
+        if ( cpr.exists() ) {
+            try ( InputStream in = cpr.getInputStream() ) {
+                log.info( String.format( "Resolved description of %s in %s.", a, cpr ) );
+                String description = StreamUtils.copyToString( in, StandardCharsets.UTF_8 );
+                descriptionsCache.put( a.getName(), description );
+                return description;
+            } catch ( IOException e ) {
+                throw new RuntimeException( e );
+            }
+        }
+        return super.resolveDescription( a, annotations, schema );
+    }
+}

gemma-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolverRegistrationListener.java

@@ -0,0 +1,43 @@
+package ubic.gemma.web.services.rest.swagger.resolver;
+
+import io.swagger.v3.core.converter.ModelConverters;
+import lombok.extern.apachecommons.CommonsLog;
+import org.apache.commons.lang3.tuple.Pair;
+import org.springframework.context.ApplicationContext;
+import org.springframework.web.context.support.WebApplicationContextUtils;
+
+import javax.servlet.ServletContextEvent;
+import javax.servlet.ServletContextListener;
+import javax.servlet.annotation.WebListener;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * Registers our customized {@link io.swagger.v3.core.jackson.ModelResolver}.
+ *
+ * @author poirigui
+ * @see CustomModelResolver
+ */
+@CommonsLog
+@WebListener
+public class CustomModelResolverRegistrationListener implements ServletContextListener {
+
+    private CustomModelResolver customModelResolver;
+
+    @Override
+    public void contextInitialized( ServletContextEvent servletContextEvent ) {
+        ApplicationContext applicationContext = WebApplicationContextUtils.getRequiredWebApplicationContext( servletContextEvent.getServletContext() );
+        // these must be sorted by ascending precedence because addConverter prepends
+        customModelResolver = applicationContext.getBean( CustomModelResolver.class );
+        ModelConverters.getInstance().addConverter( customModelResolver );
+        log.info( String.format( "Registered %s to Swagger's custom model converters.", customModelResolver ) );
+    }
+
+    @Override
+    public void contextDestroyed( ServletContextEvent servletContextEvent ) {
+        ModelConverters.getInstance().removeConverter( customModelResolver );
+        log.info( String.format( "Unregistered %s to Swagger's custom model converters.", customModelResolver ) );
+    }
+}

gemma-web/src/main/java/ubic/gemma/web/services/rest/util/JacksonConfig.java

@@ -5,7 +5,6 @@
 import io.swagger.v3.core.util.Json;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
-import ubic.gemma.web.services.rest.swagger.CustomModelConverter;
 
 /**
  * Configure the various beans injected in Swagger's components relating to Jackson's JSON serialization.
@@ -24,7 +23,7 @@ public ObjectMapper objectMapper() {
 
     /**
      * This is the ObjectMapper used by Swagger to generate the /openapi.json endpoint. It is defined here so that it
-     * can be accessed from {@link CustomModelConverter} implementations.
+     * can be accessed from {@link ubic.gemma.web.services.rest.swagger.resolver.CustomModelResolver}.
      */
     @Bean
     public ObjectMapper swaggerObjectMapper() {