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
This commit is part of merge request !123. Comments created here will be created in the context of that merge request.
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;
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 })
......
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;
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,
......
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 {
// 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(
......
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