Skip to content
Snippets Groups Projects
Commit c0f64d6a authored by Clayton, Brandon Scott's avatar Clayton, Brandon Scott
Browse files

Add response format examples and docs

parent 8b9ca089
No related branches found
No related tags found
2 merge requests!124Production Release | nshmp-ws-static,!123Resolves - Remove GITLAB_TOKEN Requirement and AASHTO-2023 web service -- add CSV response
Hide whitespace changes
Inline Side-by-side
src/aashto/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
+ 22
− 3
View file @ c0f64d6a
...@@ -23,6 +23,7 @@ import io.micronaut.runtime.event.annotation.EventListener; ...@@ -23,6 +23,7 @@ import io.micronaut.runtime.event.annotation.EventListener;
import io.swagger.v3.oas.annotations.Hidden; import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content; 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.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag; import io.swagger.v3.oas.annotations.tags.Tag;
...@@ -70,13 +71,24 @@ public class NetcdfController { ...@@ -70,13 +71,24 @@ public class NetcdfController {
description = "### Returns a risk-targeted design response spectrum for a " + description = "### Returns a risk-targeted design response spectrum for a " +
"user-specified latitude, longitude, and site class.\n" + "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" + "### Service Call Pattern\n" +
"This service call is slashed delimited with pattern: " + "This service call is slashed delimited with pattern: " +
"`/spectra/{longitude}/{latitude}/{siteClass}`\n" + "`/spectra/{longitude}/{latitude}/{siteClass}`\n" +
"<br><br>" + "<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") operationId = "aashto-slash")
@ApiResponse( @ApiResponse(
description = "Spatially interpolates data from https://doi.org/10.5066/P9Z206HY", description = "Spatially interpolates data from https://doi.org/10.5066/P9Z206HY",
...@@ -86,7 +98,14 @@ public class NetcdfController { ...@@ -86,7 +98,14 @@ public class NetcdfController {
mediaType = MediaType.APPLICATION_JSON, mediaType = MediaType.APPLICATION_JSON,
schema = @Schema(implementation = Response.class)), schema = @Schema(implementation = Response.class)),
@Content( @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}", @Get(uri = "/{longitude}/{latitude}/{siteClass}{?format}",
produces = { MediaType.APPLICATION_JSON, MediaType.TEXT_CSV }) produces = { MediaType.APPLICATION_JSON, MediaType.TEXT_CSV })
......
src/hazard/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfController.java
+ 119
− 18
View file @ c0f64d6a
...@@ -25,6 +25,7 @@ import io.micronaut.http.annotation.QueryValue; ...@@ -25,6 +25,7 @@ import io.micronaut.http.annotation.QueryValue;
import io.micronaut.runtime.event.annotation.EventListener; import io.micronaut.runtime.event.annotation.EventListener;
import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content; 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.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag; import io.swagger.v3.oas.annotations.tags.Tag;
...@@ -72,19 +73,42 @@ public class NetcdfController { ...@@ -72,19 +73,42 @@ public class NetcdfController {
description = "### Returns hazard curves for a " + description = "### Returns hazard curves for a " +
"user-specified latitude, longitude, site class, and IMT.\n" + "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" + "### Service call pattern\n" +
"This service call is slashed delimited with pattern: " + "This service call is slashed delimited with pattern: " +
"`/hazard/{longitude}/{latitude}/{siteClass}/{imt}`\n" + "`/hazard/{longitude}/{latitude}/{siteClass}/{imt}`\n" +
"<br><br>" + "<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") operationId = "hazard-by-imt")
@ApiResponse( @ApiResponse(
description = "Spatially interpolated hazard curves", description = "Spatially interpolated hazard curves",
responseCode = "200", responseCode = "200",
content = @Content( content = {
schema = @Schema(implementation = ResponseByImt.class))) @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}", @Get(uri = "/{longitude}/{latitude}/{siteClass}/{imt}{?format}",
produces = MediaType.APPLICATION_JSON) produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGetSlashByImt( public HttpResponse<String> doGetSlashByImt(
...@@ -111,19 +135,45 @@ public class NetcdfController { ...@@ -111,19 +135,45 @@ public class NetcdfController {
description = "### Returns hazard curves for a " + description = "### Returns hazard curves for a " +
"user-specified latitude, longitude, and site class.\n" + "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" + "### Service call pattern\n" +
"This service call is slashed delimited with pattern: " + "This service call is slashed delimited with pattern: " +
"`/hazard/{longitude}/{latitude}/{siteClass}`\n" + "`/hazard/{longitude}/{latitude}/{siteClass}`\n" +
"<br><br>" + "<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") operationId = "hazard-by-siteclass")
@ApiResponse( @ApiResponse(
description = "Spatially interpolated hazard curves", description = "Spatially interpolated hazard curves",
responseCode = "200", responseCode = "200",
content = @Content( content = {
schema = @Schema(implementation = ResponseBySiteClass.class))) @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) @Get(uri = "/{longitude}/{latitude}/{siteClass}{?format}", produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGetSlashBySite( public HttpResponse<String> doGetSlashBySite(
HttpRequest<?> request, HttpRequest<?> request,
...@@ -147,19 +197,44 @@ public class NetcdfController { ...@@ -147,19 +197,44 @@ public class NetcdfController {
description = "### Returns hazard curves for all site class for a " + description = "### Returns hazard curves for all site class for a " +
"user-specified latitude and longitude.\n" + "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" + "### Service call pattern\n" +
"This service call is slashed delimited with pattern: " + "This service call is slashed delimited with pattern: " +
"`/hazard/{longitude}/{latitude}`\n" + "`/hazard/{longitude}/{latitude}`\n" +
"<br><br>" + "<br><br>" +
"Example: `/hazard/-118/34`", "Example: `/hazard/-118/34`" +
"<br><br>" +
"Example: `/hazard/-118/34?format=CSV`",
operationId = "hazard") operationId = "hazard")
@ApiResponse( @ApiResponse(
description = "Returns static curves from the NSHM NetCDF file", description = "Returns static curves from the NSHM NetCDF file",
responseCode = "200", responseCode = "200",
content = @Content( content = {
schema = @Schema(implementation = Response.class))) @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) @Get(uri = "/{longitude}/{latitude}{?format}", produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGetSlash( public HttpResponse<String> doGetSlash(
HttpRequest<?> request, HttpRequest<?> request,
...@@ -183,20 +258,46 @@ public class NetcdfController { ...@@ -183,20 +258,46 @@ public class NetcdfController {
description = "### Returns hazard curves for a " + description = "### Returns hazard curves for a " +
"user-specified latitude, longitude, site class, and IMT.\n" + "user-specified latitude, longitude, site class, and IMT.\n" +
"Enter the latitude and longitude select the site class (optional) and " + "Enter the latitude and longitude select the site class (optional) " +
"IMT (optional), and press `Execute`.\n" + "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" + "### Service call pattern\n" +
"This service call is query based with pattern: " + "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>" + "<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") operationId = "hazard-by-imt")
@ApiResponse( @ApiResponse(
description = "Spatially interpolated hazard curves", description = "Spatially interpolated hazard curves",
responseCode = "200", responseCode = "200",
content = @Content( content = {
schema = @Schema(implementation = ResponseByImt.class))) @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) @Get(uri = "{?longitude,latitude,siteClass,imt,format}", produces = MediaType.APPLICATION_JSON)
public HttpResponse<String> doGet( public HttpResponse<String> doGet(
HttpRequest<?> request, HttpRequest<?> request,
......
src/lib/src/main/java/gov/usgs/earthquake/nshmp/netcdf/www/NetcdfWsUtils.java
+ 17
− 0
View file @ c0f64d6a
...@@ -86,6 +86,7 @@ public class NetcdfWsUtils { ...@@ -86,6 +86,7 @@ public class NetcdfWsUtils {
// Update description // Update description
var description = new StringBuilder() var description = new StringBuilder()
.append(scienceBaseMetadata.description + "\n") .append(scienceBaseMetadata.description + "\n")
.append(swaggerResponseFormatSection())
.append(serviceSection) .append(serviceSection)
.append(swaggerParameterSection(netcdfData)) .append(swaggerParameterSection(netcdfData))
.append(swaggerScienceBaseSection(scienceBaseMetadata)) .append(swaggerScienceBaseSection(scienceBaseMetadata))
...@@ -120,6 +121,22 @@ public class NetcdfWsUtils { ...@@ -120,6 +121,22 @@ public class NetcdfWsUtils {
.toString(); .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) { private static String swaggerScienceBaseSection(ScienceBaseMetadata scienceBaseMetadata) {
return new StringBuilder() return new StringBuilder()
.append( .append(
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment