Add support for adding Markdown descriptions to models in OpenAPI spec

PavlidisLab · Dec 13, 2022 · bee6291 · bee6291
1 parent 960588f
commit bee6291
Show file tree

Hide file tree

Showing 6 changed files with 32 additions and 0 deletions.
diff --git a/...-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolver.java b/...-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>

diff --git a/gemma-web/src/main/resources/restapidocs/examples/getDatasets.py b/gemma-web/src/main/resources/restapidocs/examples/getDatasets.py
diff --git a/gemma-web/src/main/resources/restapidocs/models/double.md b/gemma-web/src/main/resources/restapidocs/models/double.md
diff --git a/...esources/restapidocs/models/ubic.gemma.web.services.rest.util.args.FilterArg.md b/...esources/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`.
+
+- ``
diff --git a/.../resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.GeneArg.md b/.../resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.GeneArg.md
diff --git a/...resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.LimitArg.md b/...resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.LimitArg.md
@@ -0,0 +1 @@
+This argument limits the number of results.