Add support for adding Markdown descriptions to models in OpenAPI spec

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

@@ -101,6 +101,11 @@ protected List<String> resolveAllowableValues( Annotated a, Annotation[] annotat
     protected String resolveDescription( Annotated a, Annotation[] annotations, io.swagger.v3.oas.annotations.media.Schema schema ) {
         String description = super.resolveDescription( a, annotations, schema );
 
+        // lookup classpath (fallback)
+        if ( description == null ) {
+            description = resolveDescriptionFromClassPath( a );
+        }
+
         // append available properties to the description
         if ( FilterArg.class.isAssignableFrom( a.getRawType() ) && getGemmaExtensionProperty( schema, "filteringService" ) != null ) {
             String availableProperties = resolveAvailableProperties( schema );
@@ -118,6 +123,23 @@ private String resolveAvailableProperties( io.swagger.v3.oas.annotations.media.S
                 filteringService.getFilterableProperties().stream().map( p -> String.format( "- %s %s", p, filteringService.getFilterablePropertyType( p ).getSimpleName() ) ).collect( Collectors.joining( "\n" ) ) );
     }
 
+    private String resolveDescriptionFromClassPath( Annotated a ) {
+        if ( descriptionsCache.containsKey( a.getName() ) ) {
+            return descriptionsCache.get( a.getName() );
+        }
+        ClassPathResource cpr = new ClassPathResource( "restapidocs/models/" + a.getName() + ".md" );
+        if ( cpr.exists() ) {
+            try ( InputStream in = cpr.getInputStream() ) {
+                String description = StreamUtils.copyToString( in, StandardCharsets.UTF_8 );
+                descriptionsCache.put( a.getName(), description );
+                return description;
+            } catch ( IOException e ) {
+                throw new RuntimeException( e );
+            }
+        }
+        return null;
+    }
+
     /**
      * Retrieve the value of an OpenAPI Gemma extension property.
      * <p>

gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.FilterArg.md

@@ -0,0 +1,9 @@
+# FilterArg
+
+## Syntax
+
+The filter use a predictate structured in conjunctive normal form (CNF).
+
+Platforms can be filtered by taxon using the `taxon`.
+
+- ``

gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.LimitArg.md

@@ -0,0 +1 @@
+This argument limits the number of results.