diff --git a/src/aashto/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java b/src/aashto/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
index c523b196646fed349955246185fc054469038574..bb5bc19870dadd7c7fb864fcc397ef05489106fd 100644
--- a/src/aashto/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
+++ b/src/aashto/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
@@ -23,6 +23,7 @@ import io.micronaut.runtime.event.annotation.EventListener;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -70,13 +71,24 @@ public class NetcdfController {
description = "### Returns a risk-targeted design response spectrum for a " +
"user-specified latitude, longitude, and site class.\n" +
- "Enter the latitude and longitude select the site class, and press `Execute`.\n" +
+ "Enter the latitude and longitude, select the site class " +
+ "and format (optional), and press `Execute`.\n" +
+
+ "### Service Response Types\n" +
+ "The web service can respond in JSON or CSV format.\n" +
+ "<br><br>" +
+ "Choose the format type by adding a `format` query to the service call:" +
+ "`?format=JSON` or `?format=CSV`\n" +
+ "<br><br>" +
+ "Default: `JSON`\n\n" +
"### Service Call Pattern\n" +
"This service call is slashed delimited with pattern: " +
"`/spectra/{longitude}/{latitude}/{siteClass}`\n" +
"<br><br>" +
- "Example: `/spectra/-118/34/A`\n",
+ "Example: `/spectra/-118/34/A`\n" +
+ "<br><br>" +
+ "CSV Example: `/spectra/-118/34/A?format=CSV`\n",
operationId = "aashto-slash")
@ApiResponse(
description = "Spatially interpolates data from https://doi.org/10.5066/P9Z206HY",
@@ -86,7 +98,14 @@ public class NetcdfController {
mediaType = MediaType.APPLICATION_JSON,
schema = @Schema(implementation = Response.class)),
@Content(
- mediaType = MediaType.TEXT_CSV)
+ mediaType = MediaType.TEXT_CSV,
+ examples = @ExampleObject(
+ name = "CSV",
+ value = "AASHTO-2023 Web Service\n" +
+ "\n" +
+ "Longitude,-105.0,Latitude,40.0,SiteClass,BC\n" +
+ "Period (s),0.0,0.01,0.02,0.03,0.05,0.075, ...\n" +
+ "Spectral Acceleration (g),0.073,0.08,0.12,0.14,0.18, ...\n"))
})
@Get(uri = "/{longitude}/{latitude}/{siteClass}{?format}",
produces = { MediaType.APPLICATION_JSON, MediaType.TEXT_CSV })
diff --git a/src/hazard/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java b/src/hazard/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
index adf101692b164a5f03761284e367b21018a30935..f14d8449a2aa35055936926c95369321a10154d7 100644
--- a/src/hazard/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
+++ b/src/hazard/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
@@ -25,6 +25,7 @@ import io.micronaut.http.annotation.QueryValue;
import io.micronaut.runtime.event.annotation.EventListener;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -72,19 +73,42 @@ public class NetcdfController {
description = "### Returns hazard curves for a " +
"user-specified latitude, longitude, site class, and IMT.\n" +
- "Enter the latitude and longitude select the site class and IMT, and press `Execute`.\n" +
+ "Enter the latitude and longitude, select the site class, " +
+ "IMT, and format, and press `Execute`.\n" +
+
+ "### Service Response Types\n" +
+ "The web service can respond in JSON or CSV format.\n" +
+ "<br><br>" +
+ "Choose the format type by adding a `format` query to the service call:" +
+ "`?format=JSON` or `?format=CSV`\n" +
+ "<br><br>" +
+ "Default: `JSON`\n\n" +
"### Service call pattern\n" +
"This service call is slashed delimited with pattern: " +
"`/hazard/{longitude}/{latitude}/{siteClass}/{imt}`\n" +
"<br><br>" +
- "Example: `/hazard/-118/34/BC/PGA`",
+ "Example: `/hazard/-118/34/BC/PGA`" +
+ "<br><br>" +
+ "CSV Example: `/hazard/-118/34/BC/PGA?format=CSV`",
operationId = "hazard-by-imt")
@ApiResponse(
description = "Spatially interpolated hazard curves",
responseCode = "200",
- content = @Content(
- schema = @Schema(implementation = ResponseByImt.class)))
+ content = {
+ @Content(
+ mediaType = MediaType.APPLICATION_JSON,
+ schema = @Schema(implementation = ResponseByImt.class)),
+ @Content(
+ mediaType = MediaType.TEXT_CSV,
+ examples = @ExampleObject(
+ name = "CSV",
+ value = "Static Hazard Curves\n" +
+ "\n" +
+ "Longitude,-104.99,Latitude,39.34,SiteClass,BC,Imt,PGA\n" +
+ "Ground Motion (g),0.00233,0.0035,0.00524,0.00786,0.0118, ...\n" +
+ "Annual Frequency of Exceedence,0.036386,0.026034,0.018125,0.012197, ...\n"))
+ })
@Get(uri = "/{longitude}/{latitude}/{siteClass}/{imt}{?format}",
produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGetSlashByImt(
@@ -111,19 +135,45 @@ public class NetcdfController {
description = "### Returns hazard curves for a " +
"user-specified latitude, longitude, and site class.\n" +
- "Enter the latitude and longitude select the site class, and press `Execute`.\n" +
+ "Enter the latitude and longitude, select the site class and format (optional), " +
+ " and press `Execute`.\n" +
+
+ "### Service Response Types\n" +
+ "The web service can respond in JSON or CSV format.\n" +
+ "<br><br>" +
+ "Choose the format type by adding a `format` query to the service call:" +
+ "`?format=JSON` or `?format=CSV`\n" +
+ "<br><br>" +
+ "Default: `JSON`\n\n" +
"### Service call pattern\n" +
"This service call is slashed delimited with pattern: " +
"`/hazard/{longitude}/{latitude}/{siteClass}`\n" +
"<br><br>" +
- "Example: `/hazard/-118/34/BC`",
+ "Example: `/hazard/-118/34/BC`" +
+ "<br><br>" +
+ "Example: `/hazard/-118/34/BC?format=CSV`",
operationId = "hazard-by-siteclass")
@ApiResponse(
description = "Spatially interpolated hazard curves",
responseCode = "200",
- content = @Content(
- schema = @Schema(implementation = ResponseBySiteClass.class)))
+ content = {
+ @Content(
+ mediaType = MediaType.APPLICATION_JSON,
+ schema = @Schema(implementation = ResponseBySiteClass.class)),
+ @Content(
+ mediaType = MediaType.TEXT_CSV,
+ examples = @ExampleObject(
+ name = "CSV",
+ value = "Static Hazard Curves\n" +
+ "\n" +
+ "Longitude,-104.99,Latitude,39.34,SiteClass,BC,Imt,PGA\n" +
+ "Ground Motion (g),0.00233,0.0035,0.00524,0.00786,0.0118, ...\n" +
+ "Annual Frequency of Exceedence,0.036386,0.026034,0.018125,0.012197, ...\n" +
+ "\n" +
+ "..."))
+
+ })
@Get(uri = "/{longitude}/{latitude}/{siteClass}{?format}", produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGetSlashBySite(
HttpRequest<?> request,
@@ -147,19 +197,44 @@ public class NetcdfController {
description = "### Returns hazard curves for all site class for a " +
"user-specified latitude and longitude.\n" +
- "Enter the latitude and longitude and press `Execute`.\n" +
+ "Enter the latitude and longitude, select the format (optional), and press `Execute`.\n" +
+
+ "### Service Response Types\n" +
+ "The web service can respond in JSON or CSV format.\n" +
+ "<br><br>" +
+ "Choose the format type by adding a `format` query to the service call:" +
+ "`?format=JSON` or `?format=CSV`\n" +
+ "<br><br>" +
+ "Default: `JSON`\n\n" +
"### Service call pattern\n" +
"This service call is slashed delimited with pattern: " +
"`/hazard/{longitude}/{latitude}`\n" +
"<br><br>" +
- "Example: `/hazard/-118/34`",
+ "Example: `/hazard/-118/34`" +
+ "<br><br>" +
+ "Example: `/hazard/-118/34?format=CSV`",
operationId = "hazard")
@ApiResponse(
description = "Returns static curves from the NSHM NetCDF file",
responseCode = "200",
- content = @Content(
- schema = @Schema(implementation = Response.class)))
+ content = {
+ @Content(
+ mediaType = MediaType.APPLICATION_JSON,
+ schema = @Schema(implementation = Response.class)),
+ @Content(
+ mediaType = MediaType.TEXT_CSV,
+ examples = @ExampleObject(
+ name = "CSV",
+ value = "Static Hazard Curves\n" +
+ "\n" +
+ "Longitude,-104.99,Latitude,39.34,SiteClass,BC,Imt,PGA\n" +
+ "Ground Motion (g),0.00233,0.0035,0.00524,0.00786,0.0118, ...\n" +
+ "Annual Frequency of Exceedence,0.036386,0.026034,0.018125,0.012197, ...\n" +
+ "\n" +
+ "..."))
+
+ })
@Get(uri = "/{longitude}/{latitude}{?format}", produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGetSlash(
HttpRequest<?> request,
@@ -183,20 +258,46 @@ public class NetcdfController {
description = "### Returns hazard curves for a " +
"user-specified latitude, longitude, site class, and IMT.\n" +
- "Enter the latitude and longitude select the site class (optional) and " +
- "IMT (optional), and press `Execute`.\n" +
+ "Enter the latitude and longitude select the site class (optional) " +
+ "IMT (optional), and format (optional), and press `Execute`.\n" +
+
+ "### Service Response Types\n" +
+ "The web service can respond in JSON or CSV format.\n" +
+ "<br><br>" +
+ "Choose the format type by adding a `format` query to the service call:" +
+ "`?format=JSON` or `?format=CSV`\n" +
+ "<br><br>" +
+ "Default: `JSON`\n\n" +
"### Service call pattern\n" +
"This service call is query based with pattern: " +
- "`/hazard?longitude={number}&latitude={number}&siteClass={string}&imt={string}`\n" +
+ "`/hazard?longitude={number}&latitude={number}" +
+ "&siteClass={string}&imt={string}&format={CSV|JSON}`\n" +
"<br><br>" +
- "Example: `/hazard?longitude=-118&latitude=34&siteClass=A&imt=PGA`",
+ "Example: `/hazard?longitude=-118&latitude=34&siteClass=A&imt=PGA`" +
+ "<br><br>" +
+ "CSV Example: `/hazard?longitude=-118&latitude=34&siteClass=A&imt=PGA?format=CSV`",
operationId = "hazard-by-imt")
@ApiResponse(
description = "Spatially interpolated hazard curves",
responseCode = "200",
- content = @Content(
- schema = @Schema(implementation = ResponseByImt.class)))
+ content = {
+ @Content(
+ mediaType = MediaType.APPLICATION_JSON,
+ schema = @Schema(implementation = ResponseByImt.class)),
+ @Content(
+ mediaType = MediaType.TEXT_CSV,
+ examples = @ExampleObject(
+ name = "CSV",
+ value = "Static Hazard Curves\n" +
+ "\n" +
+ "Longitude,-104.99,Latitude,39.34,SiteClass,BC,Imt,PGA\n" +
+ "Ground Motion (g),0.00233,0.0035,0.00524,0.00786,0.0118, ...\n" +
+ "Annual Frequency of Exceedence,0.036386,0.026034,0.018125,0.012197, ...\n" +
+ "\n" +
+ "..."))
+
+ })
@Get(uri = "{?longitude,latitude,siteClass,imt,format}", produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGet(
HttpRequest<?> request,
diff --git a/src/lib/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfWsUtils.java b/src/lib/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfWsUtils.java
index 23f7740ae803b267331c55e0b5d815ea3748bde5..c4233ad557e292cf3b4a1fd20eb1a9790c8ac8fb 100644
--- a/src/lib/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfWsUtils.java
+++ b/src/lib/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfWsUtils.java
@@ -86,6 +86,7 @@ public class NetcdfWsUtils {
// Update description
var description = new StringBuilder()
.append(scienceBaseMetadata.description + "\n")
+ .append(swaggerResponseFormatSection())
.append(serviceSection)
.append(swaggerParameterSection(netcdfData))
.append(swaggerScienceBaseSection(scienceBaseMetadata))
@@ -120,6 +121,22 @@ public class NetcdfWsUtils {
.toString();
}
+ private static String swaggerResponseFormatSection() {
+ return new StringBuilder()
+ .append(
+ "<details>\n" +
+ "<summary>Response Format: CSV or JSON</summary>\n")
+ .append(
+ "The web service can respond in JSON or CSV format.\n" +
+ "<br><br>" +
+ "Choose the format type by adding a `format` query to the service call:" +
+ "`?format=JSON` or `?format=CSV`\n\n" +
+ "<br><br>" +
+ "Default: `JSON`")
+ .append("</details>")
+ .toString();
+ }
+
private static String swaggerScienceBaseSection(ScienceBaseMetadata scienceBaseMetadata) {
return new StringBuilder()
.append(