Swagger documentation

pom.xml

@@ -82,15 +82,9 @@
 		</dependency>
 
 		<dependency>
-			<groupId>io.springfox</groupId>
-			<artifactId>springfox-swagger2</artifactId>
-			<version>2.10.5</version>
-		</dependency>
-
-		<dependency>
-			<groupId>io.springfox</groupId>
-			<artifactId>springfox-swagger-ui</artifactId>
-			<version>2.10.5</version>
+			<groupId>org.springdoc</groupId>
+			<artifactId>springdoc-openapi-ui</artifactId>
+			<version>1.6.15</version>
 		</dependency>
 
 		<dependency>
@@ -99,12 +93,6 @@
 			<scope>runtime</scope>
 		</dependency>
 
-		<dependency>
-			<groupId>io.springfox</groupId>
-			<artifactId>springfox-data-rest</artifactId>
-			<version>2.10.5</version>
-		</dependency>
-
 		<dependency>
 			<groupId>io.swagger</groupId>
 			<artifactId>swagger-models</artifactId>

src/main/java/uk/ac/ebi/eva/evaseqcol/EvaSeqcolApplication.java

@@ -2,12 +2,13 @@
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.retry.annotation.EnableRetry;
 
 @SpringBootApplication
+@EnableRetry
 public class EvaSeqcolApplication {
 
 	public static void main(String[] args) {
 		SpringApplication.run(EvaSeqcolApplication.class, args);
 	}
-
 }

src/main/java/uk/ac/ebi/eva/evaseqcol/controller/admin/AdminController.java

@@ -1,5 +1,9 @@
 package uk.ac.ebi.eva.evaseqcol.controller.admin;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -10,6 +14,7 @@
 
 import uk.ac.ebi.eva.evaseqcol.exception.AssemblyNotFoundException;
 import uk.ac.ebi.eva.evaseqcol.exception.DuplicateSeqColException;
+import uk.ac.ebi.eva.evaseqcol.exception.IncorrectAccessionException;
 import uk.ac.ebi.eva.evaseqcol.service.SeqColService;
 
 import java.io.IOException;
@@ -29,21 +34,39 @@ public AdminController(SeqColService seqColService) {
     /**
      * Fetch and insert all possible seqCol objects given the assembly accession
      * NOTE: All possible means with all naming conventions that exist in the fetched assembly report*/
+    @Operation(summary = "Add new sequence collection objects",
+            description = "Given an INSDC or RefSeq accession, this endpoint will fetch the corresponding assembly " +
+                    "report and the assembly sequences FASTA file from the NCBI datasource, use them to construct " +
+                    "seqCol objects with as many naming conventions as possible (depends on the naming conventions " +
+                    "contained in the assembly report) and eventually save these seqCol objects into the database. " +
+                    "This is an authenticated endpoint, so it requires admin privileges to run it.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "seqCol object(s) successfully inserted"),
+            @ApiResponse(responseCode = "409", description = "seqCol object(s) already exist(s)"),
+            @ApiResponse(responseCode = "404", description = "Assembly not found"),
+            @ApiResponse(responseCode = "400", description = "Bad request. (It can be a bad accession value)"),
+            @ApiResponse(responseCode = "500", description = "Server Error")
+    })
     @PutMapping(value = "/seqcols/{asmAccession}")
     public ResponseEntity<?> fetchAndInsertSeqColByAssemblyAccession(
-            @PathVariable String asmAccession) {
+            @Parameter(name = "asmAccession",
+            description = "INSDC or RefSeq assembly accession",
+            example = "GCA_000146045.2",
+            required = true) @PathVariable String asmAccession) {
         try {
             List<String> level0Digests = seqColService.fetchAndInsertAllSeqColByAssemblyAccession(asmAccession);
             return new ResponseEntity<>(
                     "Successfully inserted seqCol object(s) for assembly accession " + asmAccession + "\nSeqCol digests=" + level0Digests
                     , HttpStatus.OK);
+        } catch (IncorrectAccessionException e) {
+            return new ResponseEntity<>(e.getMessage(), HttpStatus.BAD_REQUEST);
         } catch (IllegalArgumentException e) {
             return new ResponseEntity<>(e.getMessage(), HttpStatus.BAD_REQUEST);
         }
         catch (IOException e) {
             return new ResponseEntity<>(e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
         } catch (DuplicateSeqColException e) {
-            return new ResponseEntity<>(e.getMessage(), HttpStatus.OK);
+            return new ResponseEntity<>(e.getMessage(), HttpStatus.CONFLICT);
         } catch (AssemblyNotFoundException e) {
             return new ResponseEntity<>(e.getMessage(), HttpStatus.NOT_FOUND);
         }

src/main/java/uk/ac/ebi/eva/evaseqcol/controller/seqcol/SeqColComparisonController.java

@@ -1,5 +1,9 @@
 package uk.ac.ebi.eva.evaseqcol.controller.seqcol;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -28,9 +32,28 @@ public SeqColComparisonController(SeqColService seqColService) {
         this.seqColService = seqColService;
     }
 
+    @Operation(summary = "Compare two local sequence collection objects",
+    description = "Given two seqCol's level 0 digests, this endpoint will try to fetch the two corresponding seqCol " +
+            "objects from the database, compare them and give back the result of this comparison as defined in " +
+            "https://github.com/ga4gh/seqcol-spec/blob/master/docs/decision_record.md#2022-06-15---structure-for-the-return-value-of-the-comparison-api-endpoint")
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "Comparison has completed successfully"),
+            @ApiResponse(responseCode = "404", description = "One of the compared seqCol object was not found"),
+            @ApiResponse(responseCode = "500", description = "Server error. Maybe it's related to the seqCol Map fields")
+    })
     @GetMapping("/{digest1}/{digest2}")
     public ResponseEntity<?> compareSequenceCollections(
-            @PathVariable String digest1, @PathVariable String digest2) {
+            @Parameter(name = "digest1",
+                    description = "Level 0 digest of seqColA",
+                    example = "3mTg0tAA3PS-R1TzelLVWJ2ilUzoWfVq",
+                    required = true
+
+            ) @PathVariable String digest1,@Parameter(name = "digest2",
+            description = "Level 0 digest of seqColB",
+            example = "rkTW1yZ0e22IN8K-0frqoGOMT8dynNyE",
+            required = true
+
+    ) @PathVariable String digest2) {
         try {
             SeqColComparisonResultEntity comparisonResult = seqColService.compareSeqCols(digest1, digest2);
             return new ResponseEntity<>(comparisonResult, HttpStatus.OK);
@@ -44,9 +67,25 @@ public ResponseEntity<?> compareSequenceCollections(
         }
     }
 
+    @Operation(summary = "Compare a local sequence collection object with a provided one",
+    description = "Given a seqCol's level 0 digest and a JSON representation of another seqCol level 2 object provided" +
+            "in the POST request's body,this endpoint will try to fetch the seqCol object with the given digest " +
+            "from the db, compare it with the provided one and give back the result of this comparison as defined in " +
+            "https://github.com/ga4gh/seqcol-spec/blob/master/docs/decision_record.md#2022-06-15---structure-for-the-return-value-of-the-comparison-api-endpoint")
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "Comparison has completed successfully"),
+            @ApiResponse(responseCode = "404", description = "Could not find a seqCol object with the given digest"),
+            @ApiResponse(responseCode = "500", description = "Server Error")
+    })
     @PostMapping("/{digest1}")
     public ResponseEntity<?> compareSequenceCollections(
-            @PathVariable String digest1, @RequestBody TreeMap<String, List<String>> seqColLevelTwo
+            @Parameter(name = "digest1",
+            description = "Level 0 digest of seqColA",
+            example = "3mTg0tAA3PS-R1TzelLVWJ2ilUzoWfVq",
+            required = true) @PathVariable String digest1,
+            @Parameter(name = "seqColLevelTwo",
+            description = "SeqCol object level 2",
+            required = true) @RequestBody TreeMap<String, List<String>> seqColLevelTwo
     ) {
         try {
             SeqColComparisonResultEntity comparisonResult = seqColService.compareSeqCols(digest1, seqColLevelTwo);

src/main/java/uk/ac/ebi/eva/evaseqcol/controller/seqcol/SeqColController.java

@@ -1,5 +1,9 @@
 package uk.ac.ebi.eva.evaseqcol.controller.seqcol;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -9,7 +13,6 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-import uk.ac.ebi.eva.evaseqcol.entities.SeqColEntity;
 import uk.ac.ebi.eva.evaseqcol.entities.SeqColLevelOneEntity;
 import uk.ac.ebi.eva.evaseqcol.entities.SeqColLevelTwoEntity;
 import uk.ac.ebi.eva.evaseqcol.exception.SeqColNotFoundException;
@@ -31,9 +34,25 @@ public SeqColController(SeqColService seqColService) {
         this.seqColService = seqColService;
     }
 
+    @Operation(summary = "Retrieve seqCol object by digest",
+    description = "Given a seqCol's level 0 digest, this endpoint will try to fetch the corresponding seqCol object from" +
+            " the database and return it in the specified level. The default level value is 1.")
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "SeqCol was returned successfully"),
+            @ApiResponse(responseCode = "404", description = "Could not find a seqCol object with the given digest"),
+            @ApiResponse(responseCode = "400", description = "Not valid level value"),
+            @ApiResponse(responseCode = "500", description = "Server Error")
+    })
     @GetMapping(value = "/collection/{digest}")
     public ResponseEntity<?> getSeqColByDigestAndLevel(
-            @PathVariable String digest, @RequestParam(required = false) String level) {
+            @Parameter(name = "digest",
+            description = "SeqCol's level 0 digest",
+            example = "3mTg0tAA3PS-R1TzelLVWJ2ilUzoWfVq",
+            required = true) @PathVariable String digest,
+            @Parameter(name = "level",
+            description = "The desired output's level (1 or 2)",
+            example = "1",
+            required = false) @RequestParam(required = false) String level) {
         if (level == null) level = "none";
         try {
             switch (level) {

src/main/java/uk/ac/ebi/eva/evaseqcol/controller/swagger/SwaggerConfig.java

@@ -0,0 +1,37 @@
+package uk.ac.ebi.eva.evaseqcol.controller.swagger;
+
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
+
+@Configuration
+public class SwaggerConfig extends WebMvcConfigurerAdapter {
+
+    @Autowired
+    private SwaggerInterceptAdapter interceptAdapter;
+
+    @Bean
+    public OpenAPI seqColOpenAPI() {
+        return new OpenAPI()
+                .info(new Info().title("Sequence Collections API")
+                              .description("A service that provides a standardized way to identify sequence collections." +
+                                                   "\nThe endpoints of this API provide a service for ingestion of seqCol" +
+                                                   "objects, a service for the retrieval of seqCol objects given their " +
+                                                   "level 0 digests and a service for the comparison of two seqCol objects.")
+                              .version("v1.0")
+                              .license(new License().name("Apache-2.0").url("https://raw.githubusercontent.com/EBIvariation/eva-seqcol/main/LICENSE"))
+                              .contact(new Contact().name("GitHub Repository").url("https://github.com/EBIvariation/eva-seqcol").email(null)));
+    }
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        registry.addInterceptor(interceptAdapter);
+    }
+}

src/main/java/uk/ac/ebi/eva/evaseqcol/controller/swagger/SwaggerInterceptAdapter.java

@@ -0,0 +1,32 @@
+package uk.ac.ebi.eva.evaseqcol.controller.swagger;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.handler.HandlerInterceptorAdapter;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+@Component
+public class SwaggerInterceptAdapter extends HandlerInterceptorAdapter {
+
+    @Value("${server.servlet.context-path:/}")
+    private String contextPath;
+
+    @Override
+    /**
+     * Redirecting to the swagger home page*/
+    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
+                             Object handler) throws Exception {
+        String req = request.getRequestURI();
+
+        if (req.equals(contextPath) || req.equals(contextPath + "/") ||
+        req.equals(contextPath + "/collection") || req.equals(contextPath + "/collection/")
+                || req.equals(contextPath + "/comparison") || req.equals(contextPath + "/comparison/")) {
+            response.sendRedirect(contextPath + "/swagger-ui/index.html");
+            return false;
+        }
+
+        return super.preHandle(request, response, handler);
+    }
+}

src/main/java/uk/ac/ebi/eva/evaseqcol/service/SeqColService.java

@@ -63,7 +63,7 @@ public SeqColService(NCBISeqColDataSource ncbiSeqColDataSource, SeqColLevelOneSe
     public Optional<String> addFullSequenceCollection(SeqColLevelOneEntity levelOneEntity, List<SeqColExtendedDataEntity> extendedSeqColDataList) {
         long numSeqCols = levelOneService.countSeqColLevelOneEntitiesByDigest(levelOneEntity.getDigest());
         if (numSeqCols > 0) {
-            logger.error("SeqCol with digest " + levelOneEntity.getDigest() + " already exists !");
+            logger.warn("SeqCol with digest " + levelOneEntity.getDigest() + " already exists !");
             throw new DuplicateSeqColException(levelOneEntity.getDigest());
         } else {
             SeqColLevelOneEntity levelOneEntity1 = levelOneService.addSequenceCollectionL1(levelOneEntity).get();
@@ -79,7 +79,7 @@ public Optional<? extends SeqColEntity> getSeqColByDigestAndLevel(String digest,
        } else if (level == 2) {
             Optional<SeqColLevelOneEntity> seqColLevelOne = levelOneService.getSeqColLevelOneByDigest(digest);
             if (!seqColLevelOne.isPresent()) {
-                logger.error("No seqCol corresponding to digest " + digest + " could be found in the db");
+                logger.warn("No seqCol corresponding to digest " + digest + " could be found in the db");
                 throw new SeqColNotFoundException(digest);
             }
             SeqColLevelTwoEntity levelTwoEntity = new SeqColLevelTwoEntity().setDigest(digest);
@@ -108,7 +108,7 @@ public Optional<? extends SeqColEntity> getSeqColByDigestAndLevel(String digest,
 
            return Optional.of(levelTwoEntity);
        } else {
-           logger.error("Could not find any seqCol object with digest " + digest + " on level " + level);
+           logger.warn("Could not find any seqCol object with digest " + digest + " on level " + level);
            return Optional.empty();
        }
     }
@@ -196,7 +196,7 @@ public SeqColExtendedDataEntity retrieveExtendedLengthEntity(List<SeqColExtended
     public Optional<String> insertSeqColL1AndL2(SeqColLevelOneEntity levelOneEntity,
                                     List<SeqColExtendedDataEntity> seqColExtendedDataEntities) {
         if (isSeqColL1Present(levelOneEntity)) {
-            logger.error("Could not insert seqCol with digest " + levelOneEntity.getDigest() + ". Already exists !");
+            logger.warn("Could not insert seqCol with digest " + levelOneEntity.getDigest() + ". Already exists !");
             throw new DuplicateSeqColException(levelOneEntity.getDigest());
         } else {
             Optional<String> level0Digest = addFullSequenceCollection(levelOneEntity, seqColExtendedDataEntities);
@@ -215,11 +215,11 @@ public SeqColComparisonResultEntity compareSeqCols(String seqColADigest, String
         Optional<SeqColLevelTwoEntity> seqColAEntity = levelTwoService.getSeqColLevelTwoByDigest(seqColADigest);
         Optional<SeqColLevelTwoEntity> seqColBEntity = levelTwoService.getSeqColLevelTwoByDigest(seqColBDigest);
         if (!seqColAEntity.isPresent()) {
-            logger.error("No seqCol corresponding to digest " + seqColADigest + " could be found in the db");
+            logger.warn("No seqCol corresponding to digest " + seqColADigest + " could be found in the db");
             throw new SeqColNotFoundException(seqColADigest);
         }
         if (!seqColBEntity.isPresent()) {
-            logger.error("No seqCol corresponding to digest " + seqColBDigest + " could be found in the db");
+            logger.warn("No seqCol corresponding to digest " + seqColBDigest + " could be found in the db");
             throw new SeqColNotFoundException(seqColBDigest);
         }
         return compareSeqCols(seqColADigest, seqColAEntity.get(), seqColBDigest, seqColBEntity.get());

src/main/resources/application.properties

@@ -33,3 +33,11 @@ service.info.file.path=src/main/resources/static/service-info.json
 spring.data.rest.detection-strategy=annotated
 
 spring.data.rest.basePath=/api
+
+# Swagger Configuration
+springdoc.swagger-ui.path=/seqcol-documentation
+springdoc.api-docs.path=/seqcol-api-docs
+
+springdoc.packages-to-scan=uk.ac.ebi.eva.evaseqcol.controller
+springdoc.swagger-ui.operationsSorter=method
+springdoc.swagger-ui.tagsSorter=alpha