From bee62918b8babf0ae69e6f60575ccc8a16ca0acc Mon Sep 17 00:00:00 2001 From: Guillaume Poirier-Morency Date: Tue, 13 Dec 2022 16:02:46 -0500 Subject: [PATCH] Add support for adding Markdown descriptions to models in OpenAPI spec --- .../swagger/resolver/CustomModelResolver.java | 22 +++++++++++++++++++ .../restapidocs/examples/getDatasets.py | 0 .../resources/restapidocs/models/double.md | 0 ...a.web.services.rest.util.args.FilterArg.md | 9 ++++++++ ...mma.web.services.rest.util.args.GeneArg.md | 0 ...ma.web.services.rest.util.args.LimitArg.md | 1 + 6 files changed, 32 insertions(+) create mode 100644 gemma-web/src/main/resources/restapidocs/examples/getDatasets.py create mode 100644 gemma-web/src/main/resources/restapidocs/models/double.md create mode 100644 gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.FilterArg.md create mode 100644 gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.GeneArg.md create mode 100644 gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.LimitArg.md diff --git a/gemma-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolver.java b/gemma-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolver.java index cc6dd9a8a4..4b6326f9fb 100644 --- a/gemma-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolver.java +++ b/gemma-web/src/main/java/ubic/gemma/web/services/rest/swagger/resolver/CustomModelResolver.java @@ -101,6 +101,11 @@ protected List 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. *

diff --git a/gemma-web/src/main/resources/restapidocs/examples/getDatasets.py b/gemma-web/src/main/resources/restapidocs/examples/getDatasets.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/gemma-web/src/main/resources/restapidocs/models/double.md b/gemma-web/src/main/resources/restapidocs/models/double.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.FilterArg.md b/gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.FilterArg.md new file mode 100644 index 0000000000..884602ddcd --- /dev/null +++ b/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`. + +- `` \ No newline at end of file diff --git a/gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.GeneArg.md b/gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.GeneArg.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.LimitArg.md b/gemma-web/src/main/resources/restapidocs/models/ubic.gemma.web.services.rest.util.args.LimitArg.md new file mode 100644 index 0000000000..42ca63c42b --- /dev/null +++ b/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. \ No newline at end of file