Chore – Add OpenAPI documentation

app/src/main/java/uk/ac/ebi/atlas/experimentpage/cellplot/JsonCellPlotController.java

@@ -1,6 +1,11 @@
 package uk.ac.ebi.atlas.experimentpage.cellplot;
 
 import com.google.common.collect.ImmutableMap;
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.springframework.http.MediaType;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -60,6 +65,51 @@ else if (!parameterisations.contains(requestParams.get(requiredParameter))) {
 
     @GetMapping(value = "/clusters/k/{k}",
                 produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
+    @Operation(
+            operationId = "clustersCellPlot",
+            description = "Retrieve cells from a dataset as a 2D projection bucketed by clusters as predicted by " +
+                    "[Scanpy](https://scanpy.readthedocs.io); each point represents a cell in the experiment. Data " +
+                    "are returned in the [Highcharts scatter plot format]" +
+                    "(https://api.highcharts.com/highcharts/series.scatter.data). Each series represents a " +
+                    "different cluster value. There will be as many clusters/series as `k` (see below).",
+            parameters = {
+                    @Parameter(
+                            name = "experimentAccession",
+                            in = ParameterIn.PATH,
+                            description = "experiment accession of dataset",
+                            example = "E-MTAB-5061"),
+                    @Parameter(
+                            name = "k",
+                            in = ParameterIn.PATH,
+                            description = "number of clusters in which the cells should be split",
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "9"
+                            )),
+                    @Parameter(
+                            name = "plotMethod",
+                            in = ParameterIn.QUERY,
+                            description = "2D projection method",
+                            schema = @Schema(
+                                    defaultValue = "umap",
+                                    allowableValues = {"umap", "tsne"})),
+                    @Parameter(
+                            name = "n_neighbors",
+                            in = ParameterIn.QUERY,
+                            description = "number of neighbours for the UMAP projection (ignored in t-SNE plots)",
+                            required = true,
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "20")),
+                    @Parameter(
+                            name = "perplexity",
+                            in = ParameterIn.QUERY,
+                            description = "perplexity value for the t-SNE projection (ignored in UMAP plots)",
+                            required = true,
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "35"))
+            })
     public String clusterPlotK(@PathVariable String experimentAccession,
                                @PathVariable int k,
                                @RequestParam String plotMethod,
@@ -74,6 +124,47 @@ public String clusterPlotK(@PathVariable String experimentAccession,
 
     @GetMapping(value = "/clusters/metadata/{metadata}",
                 produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
+    @Operation(
+            operationId = "metadataCellPlot",
+            description = "Retrieve cells from a dataset as a 2D projection bucketed by a metadata field; each " +
+                    "point represents a cell in the experiment. Data are returned in the [Highcharts scatter plot " +
+                    "format](https://api.highcharts.com/highcharts/series.scatter.data). Each series represents a " +
+                    "value of the cell plots that share it for the specifed metadata field.",
+            parameters = {
+                    @Parameter(
+                            name = "experimentAccession",
+                            in = ParameterIn.PATH,
+                            description = "experiment accession of dataset",
+                            example = "E-MTAB-5061"),
+                    @Parameter(
+                            name = "metadata",
+                            in = ParameterIn.PATH,
+                            description = "metadata field name over which cells should be bucketed",
+                            example = "inferred cell type - ontology labels"),
+                    @Parameter(
+                            name = "plotMethod",
+                            in = ParameterIn.QUERY,
+                            description = "2D projection method",
+                            schema = @Schema(
+                                    defaultValue = "umap",
+                                    allowableValues = {"umap", "tsne" })),
+                    @Parameter(
+                            name = "n_neighbors",
+                            in = ParameterIn.QUERY,
+                            description = "number of neighbours for the UMAP projection (ignored in t-SNE plots)",
+                            required = true,
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "20")),
+                    @Parameter(
+                            name = "perplexity",
+                            in = ParameterIn.QUERY,
+                            description = "perplexity value for the t-SNE projection (ignored in UMAP plots)",
+                            required = true,
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "35"))
+            })
     public String clusterPlotMetadata(@PathVariable String experimentAccession,
                                       @PathVariable String metadata,
                                       @RequestParam String plotMethod,
@@ -86,6 +177,7 @@ public String clusterPlotMetadata(@PathVariable String experimentAccession,
                 requestParams.getOrDefault("accessKey", ""));
     }
 
+    @Hidden
     @GetMapping(value = "/expression",
                 produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
     public String expressionPlot(@PathVariable String experimentAccession,
@@ -103,6 +195,48 @@ public String expressionPlot(@PathVariable String experimentAccession,
     // See also JsonBioentityInformationController.java
     @GetMapping(value = "/expression/{geneId:.+}",
                 produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
+    @Operation(
+            operationId = "expressionCellPlot",
+            description = "Retrieve expression of a specified gene ID from a dataset as a 2D projection; each " +
+                    "point represents a cell in the experiment. The data is returned in the [Highcharts scatter " +
+                    "plot](https://api.highcharts.com/highcharts/series.scatter.data) format in a single series.",
+            parameters = {
+                    @Parameter(
+                            name = "experimentAccession",
+                            in = ParameterIn.PATH,
+                            description = "experiment accession of dataset",
+                            example = "E-MTAB-5061"),
+                    @Parameter(
+                            name = "geneId",
+                            in = ParameterIn.PATH,
+                            description = "[Ensembl](https://www.ensembl.org) gene ID to show expression of (may " +
+                                    "be empty, in which case plot   will show no expression in all cells)",
+                            example = "ENSG00000125798"),
+                    @Parameter(
+                            name = "plotMethod",
+                            in = ParameterIn.QUERY,
+                            description = "2D projection method",
+                            schema = @Schema(
+                                    type = "string",
+                                    defaultValue = "umap",
+                                    allowableValues = {"umap", "tsne"})),
+                    @Parameter(
+                            name = "n_neighbors",
+                            in = ParameterIn.QUERY,
+                            description = "number of neighbours for the UMAP projection (ignored in t-SNE plots)",
+                            required = true,
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "20")),
+                    @Parameter(
+                            name = "perplexity",
+                            in = ParameterIn.QUERY,
+                            description = "perplexity value for the t-SNE projection (ignored in UMAP plots)",
+                            required = true,
+                            schema = @Schema(
+                                    type = "integer",
+                                    example = "35"))
+            })
     public String expressionPlot(@PathVariable String experimentAccession,
                                  @PathVariable String geneId,
                                  @RequestParam String plotMethod,

app/src/main/java/uk/ac/ebi/atlas/trader/ScxaExperimentRepository.java

@@ -57,4 +57,10 @@ public Experiment getExperiment(String experimentAccession) {
                 idfParser.parse(experimentDto.getExperimentAccession()),
                 sdrfParser.parseSingleCellTechnologyType(experimentDto.getExperimentAccession()));
     }
+
+    @Override
+    public String getExperimentType(String experimentAccession) {
+        return experimentCrudDao.getExperimentType(experimentAccession);
+    }
+
 }

buildSrc/src/main/groovy/atlas-web-app.java-conventions.gradle

@@ -22,6 +22,8 @@ repositories {
 }
 
 dependencies {
+  implementation 'io.swagger.core.v3:swagger-core:2.1.11'
+
   implementation 'javax.inject:javax.inject:1'
   implementation 'javax.annotation:javax.annotation-api:1.3.2'
   // Needs to match Tomcat version https://tomcat.apache.org/whichversion.html

docker/docker-compose-openapi.yml

@@ -0,0 +1,51 @@
+version: "3.6"
+
+services:
+  scxa-gradle:
+    image: openjdk:11
+    container_name: scxa-gradle
+    networks:
+      - scxa
+    ports:
+      - "8081:8081"
+    working_dir: /root/project
+    volumes:
+      - root-gradle-wrapper:/root/.gradle/wrapper
+      - root-gradle-caches:/root/.gradle/caches
+      - ..:/root/project
+      - ./packages:/root/.m2
+      - $GRADLE_RO_DEP_CACHE:/gradle-ro-dep-cache
+      - $ATLAS_EXPERIMENTS_PATH:/sc-experiments
+      - $ATLAS_BIOENTITY_PROPERTIES_PATH:/atlas-data/bioentity_properties
+
+    depends_on:
+      - scxa-postgres
+      - scxa-solrcloud-1
+      - scxa-solrcloud-2
+    environment:
+      POSTGRES_HOST: $POSTGRES_HOST
+      POSTGRES_DB: $POSTGRES_DB
+      POSTGRES_USER: $POSTGRES_USER
+      POSTGRES_PASSWORD: $POSTGRES_PASSWORD
+      GRADLE_RO_DEP_CACHE: /gradle-ro-dep-cache
+    command:
+      - sh
+      - -c
+      - >
+        ./gradlew
+        -PdataFilesLocation=/atlas-data
+        -PexperimentFilesLocation=/sc-experiments
+        -PjdbcUrl=jdbc:postgresql://$POSTGRES_HOST:5432/$POSTGRES_DB
+        -PjdbcUsername=$POSTGRES_USER
+        -PjdbcPassword=$POSTGRES_PASSWORD
+        -PzkHost=scxa-zk-1
+        -PsolrHost=scxa-solrcloud-1
+        clean :openapi:bootRun
+
+volumes:
+  root-gradle-wrapper:
+  root-gradle-caches:
+
+networks:
+  scxa:
+    name: scxa

openapi/README.md

@@ -0,0 +1,55 @@
+# Open API
+
+This subproject generates Open API documentation for all controllers in `app` and `atlas-web-ocre` subprojects. It is
+powered by [springdoc-openapi](https://springdoc.org/) and 
+[its Gradle plugin](https://github.com/springdoc/springdoc-openapi-gradle-plugin). It is a Spring Boot minimal web app
+that includes the two mentioned projects and finds all the relevant URLs by virtue of package scanning.
+
+## Requirements
+- Java 11
+- Expression Atlas environment (PostgreSQL server; SolrCloud cluster; bioentity annotation and experiment files)
+
+## Usage
+### Swagger UI
+```bash
+./gradlew :openapi:bootRun
+```
+
+Launch your browser and point it at `http://localhost:8081/swagger-ui.html`. Also, you can find your API docs at 
+`http://localhost:8081/v3/api-docs.yaml` (YAML) or `http://localhost:8081/v3/api-docs` (JSON).
+
+### Generate API docs
+```bash
+./gradlew :openapi:generateOpenApiDocs
+```
+
+Find your Open API doc at `openapi/build/openapi.yaml`.
+
+## Configuration
+Configuration variables are set with `-Dproperty=value` if you run the application via `java -jar ...`, or by adding
+`-Pproperty=value` to the Gradle task (in the tables below: Java property name, and Gradle propery name, respectively).
+
+**IMPORTANT**: At the very least you will need to set the environment variables described in the Default value columns
+to run/compile the application with Gradle. However, notice that the `-D` arguments will override whatever was set at
+compile time, so if you forget or your environment changes, you don’t need to recompile.
+
+### Expression Atlas file options: `configuration.properties`
+| Java property name          | Gradle property name      | Default value               |
+|-----------------------------|---------------------------|-----------------------------|
+| `data.files.location`       | `dataFilesLocation`       | `${ATLAS_DATA_PATH}`        |
+| `experiment.files.location` | `experimentFilesLocation` | `${ATLAS_EXPERIMENTS_PATH}` |
+
+### Expression Atlas database options: `jdbc.properties`
+| Java Property name | Gradle property name | Default value                                                       |
+|--------------------|----------------------|---------------------------------------------------------------------|
+| `jdbc.url`         | `jdbcUrl`            | `jdbc:postgresql://${ATLAS_POSTGRES_HOST}:5432/${ATLAS_POSTGRES_DB` |
+| `jdbc.username`    | `jdbcUsername`       | `${ATLAS_POSTGRES_USER}`                                            |
+| `jdbc.password`    | `jdbcPassword`       | `${ATLAS_POSTRES_PASSWORD}`                                         |
+
+### Expression Atlas Solr options: `solr.properties`
+| Java property name | Gradle property name | Default value        |
+|--------------------|----------------------|----------------------|
+| `zk.host`          | `zkHost`             | `${ATLAS_ZK_HOST}`   |
+| `zk.port`          | `zkPort`             | `2181`               |
+| `solr.host`        | `solrHost`           | `${ATLAS_SOLR_HOST}` |
+| `solr.port`        | `solrPort`           | `8983`               |