From 15558ff29ac80870c4182addc3b7c14c661efe5b Mon Sep 17 00:00:00 2001
From: Enrico Ottonello <enrico.ottonello@isti.cnr.it>
Date: Wed, 31 Aug 2022 14:06:10 +0200
Subject: [PATCH] added oas ve annotations; added example values for scraping
 method

---
 .../bioschemas/api/MainApplication.java       | 22 ++++++++++++++++---
 .../controller/BioschemasAPIController.java   | 15 +++++++++++--
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/MainApplication.java b/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/MainApplication.java
index 7a57b29b..d8078ce9 100644
--- a/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/MainApplication.java
+++ b/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/MainApplication.java
@@ -1,5 +1,6 @@
 package eu.dnetlib.bioschemas.api;
 
+import io.swagger.v3.oas.models.tags.Tag;
 import org.springdoc.core.GroupedOpenApi;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
@@ -10,12 +11,17 @@ import org.springframework.scheduling.annotation.EnableScheduling;
 
 import eu.dnetlib.common.app.AbstractDnetApp;
 
+import java.util.Arrays;
+import java.util.List;
+
 @SpringBootApplication
 @EnableCaching
 @EnableScheduling
 @ComponentScan(basePackages = "eu.dnetlib")
 public class MainApplication extends AbstractDnetApp {
 
+	public static final String BIOSCHEMAS_APIS = "D-Net Bioschemas Service APIs";
+
 	public static void main(final String[] args) {
 		SpringApplication.run(MainApplication.class, args);
 	}
@@ -23,14 +29,24 @@ public class MainApplication extends AbstractDnetApp {
 	@Bean
 	public GroupedOpenApi publicApi() {
 		return GroupedOpenApi.builder()
-			.group("D-Net Bioschemas Service APIs")
-			.pathsToMatch("**/api/**")
+			.group(BIOSCHEMAS_APIS)
+			.pathsToMatch("/api/**")
 			.build();
 	}
 
 	@Override
 	protected String swaggerTitle() {
-		return "D-Net Bioschemas Service APIs";
+		return BIOSCHEMAS_APIS;
+	}
+
+	@Override
+	protected List<Tag> swaggerTags() {
+		return Arrays.asList(new Tag().name(BIOSCHEMAS_APIS).description(BIOSCHEMAS_APIS));
+	}
+
+	@Override
+	protected String swaggerDesc() {
+		return BIOSCHEMAS_APIS;
 	}
 
 }
diff --git a/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/controller/BioschemasAPIController.java b/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/controller/BioschemasAPIController.java
index e4773f9f..2deed3fa 100644
--- a/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/controller/BioschemasAPIController.java
+++ b/apps/bioschemas-api/src/main/java/eu/dnetlib/bioschemas/api/controller/BioschemasAPIController.java
@@ -1,9 +1,14 @@
 package eu.dnetlib.bioschemas.api.controller;
 
+import eu.dnetlib.bioschemas.api.MainApplication;
 import eu.dnetlib.bioschemas.api.scraper.ScrapingExecution;
 import eu.dnetlib.bioschemas.api.scraper.ScrapingExecutor;
 import eu.dnetlib.bioschemas.api.utils.BioschemasException;
 import eu.dnetlib.common.controller.AbstractDnetController;
+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.tags.Tag;
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.LineIterator;
 import org.apache.commons.logging.Log;
@@ -27,6 +32,7 @@ import java.nio.charset.StandardCharsets;
 
 @RestController
 @RequestMapping("/api")
+@Tag(name = MainApplication.BIOSCHEMAS_APIS)
 public class BioschemasAPIController extends AbstractDnetController {
 
 	@Value("${outputFolder}")
@@ -41,19 +47,24 @@ public class BioschemasAPIController extends AbstractDnetController {
 
 	private static final Log log = LogFactory.getLog(BioschemasAPIController.class);
 
+	@Operation(summary = "start the scraping operation", description = "<H1>Working input values are in the following table</H1><BR><TABLE><TR><TH>datasourceKey</TH><TH>sitemapUrl</TH></TR><TR><TD>ped</TD><TD>https://proteinensemble.org/sitemap2.xml.gz</TD></TR><TR><TD>disprot</TD><TD>https://disprot.org/sitemap2.xml.gz</TD></TR><TR><TD>mobidb</TD><TD>https://mobidb.org/sitemap2.xml.gz</TD></TR></TABLE>")
 	@GetMapping("/startScraping")
-	public ScrapingExecution startScraping(@RequestParam final String datasourceKey, @RequestParam final String sitemapUrl, final HttpServletRequest req) {
+	public ScrapingExecution startScraping(@Parameter(name = "datasourceKey") @RequestParam final String datasourceKey,
+										   @Parameter(name = "sitemapUrl") @RequestParam final String sitemapUrl,
+										   final HttpServletRequest req) {
 		logger.info("<STARTSCRAPING> datasourceKey: "+datasourceKey+" sitemapUrl:"+sitemapUrl);
 		return scrapingExecutor.startScraping(datasourceKey, sitemapUrl, getOutputDataPattern(), req.getRemoteAddr(), getOutputFolder());
 	}
 
+	@Operation(summary = "check the status of last scraping operation")
 	@GetMapping("/startScraping/status")
 	public final ScrapingExecution statusScraping() {
 		return scrapingExecutor.getLastScrapingExecution();
 	}
 
+	@Operation(summary = "retrieve the nquads downloaded for one specific provider")
 	@RequestMapping(value = "/getNQuads", method = RequestMethod.GET)
-	public String getNQuads(@RequestParam final String datasourceKey, HttpServletResponse response) throws BioschemasException, IOException {
+	public String getNQuads(@Parameter(name =  "datasourceKey") @RequestParam final String datasourceKey, HttpServletResponse response) throws BioschemasException, IOException {
 
 		logger.info("<GETNQUADS> datasourceKey: "+datasourceKey);