diff --git a/api.mapserv.utah.gov/Controllers/CanaryController.cs b/api.mapserv.utah.gov/Controllers/CanaryController.cs index 47d19c5e..0595a4f1 100644 --- a/api.mapserv.utah.gov/Controllers/CanaryController.cs +++ b/api.mapserv.utah.gov/Controllers/CanaryController.cs @@ -10,6 +10,7 @@ namespace api.mapserv.utah.gov.Controllers { [ApiVersion("1.0")] + [ApiExplorerSettings(IgnoreApi = true)] [Produces("application/json")] public class CanaryController : Controller { diff --git a/api.mapserv.utah.gov/Controllers/GeocodeAddressController.cs b/api.mapserv.utah.gov/Controllers/GeocodeAddressController.cs index 87f84ec1..2851681d 100644 --- a/api.mapserv.utah.gov/Controllers/GeocodeAddressController.cs +++ b/api.mapserv.utah.gov/Controllers/GeocodeAddressController.cs @@ -20,6 +20,12 @@ namespace api.mapserv.utah.gov.Controllers { + /// + /// Geocoding API Methods + /// + /// + /// API methods for finding a geolocation (x,y) for addresses. + /// [ApiController] [ApiVersion("1.0")] [Produces("application/json")] @@ -53,10 +59,19 @@ public GeocodeAddressController(ParseAddressCommand parseAddressCommand, ParseZo _reverseGeocodeCommand = reverseGeocodeAddressCommand; } + /// + /// Finds the x, y location for an input address + /// + /// Requires an API Key + /// The address was geocoded successfully + /// The input address was not well formed + /// The input address was unable to be geocoded + /// A Utah street address. eg: 326 east south temple st. Intersections are separated by `and` + /// A Utah municipality name or 5 digit zip code + /// [HttpGet] - [Produces("application/json")] [ProducesResponseType(200, Type = typeof(ApiResponseContainer))] - [ProducesResponseType(400, Type = typeof(ApiResponseContainer))] + [ProducesResponseType(400, Type = typeof(ApiResponseContainer))] [ProducesResponseType(404, Type = typeof(ApiResponseContainer))] [Route("api/v{version:apiVersion}/geocode/{street}/{zone}")] public async Task Get(string street, string zone, [FromQuery] GeocodingOptions options) @@ -226,43 +241,23 @@ public async Task Get(string street, string zone, [FromQuery] Geoc }); } + /// + /// Finds the nearest address to the input location + /// + /// Requires an API Key + /// An address was found near the input location + /// The input location was not well formed + /// No house address could be found within the distance supplied from the input location + /// A geographic coordinate representing the longitude or easting + /// A geographic coordinate representing the latitdue or northing + /// [HttpGet] - [Produces("application/json")] [ProducesResponseType(200, Type = typeof(ApiResponseContainer))] - [ProducesResponseType(400, Type = typeof(ApiResponseContainer))] + [ProducesResponseType(400, Type = typeof(ApiResponseContainer))] [ProducesResponseType(404, Type = typeof(ApiResponseContainer))] [Route("api/v{version:apiVersion}/geocode/reverse/{x:double}/{y:double}")] public async Task Reverse(double x, double y, [FromQuery] ReverseGeocodingOptions options) { - //#region validation - - //var errors = ""; - //if (!xIn.HasValue) - //{ - // errors = "X is empty. "; - //} - - //if (!yIn.HasValue) - //{ - // errors += "Y is emtpy"; - //} - - //if (errors.Length > 0) - //{ - // Log.Debug("Bad reverse geocode request", errors); - - // return BadRequest(new ApiResponseContainer - // { - // Status = (int)HttpStatusCode.BadRequest, - // Message = errors - // }); - //} - - //#endregion - - //var x = xIn.Value; - //var y = yIn.Value; - if (options.SpatialReference != 26912) { _reprojectCommnd.Initialize(new ReprojectPointsCommand.PointProjectQueryArgs(options.SpatialReference, 26912, new [] { x, y })); diff --git a/api.mapserv.utah.gov/Controllers/ValuesController.cs b/api.mapserv.utah.gov/Controllers/ValuesController.cs index 4cc4e6b3..e39faeb9 100644 --- a/api.mapserv.utah.gov/Controllers/ValuesController.cs +++ b/api.mapserv.utah.gov/Controllers/ValuesController.cs @@ -7,6 +7,7 @@ namespace api.mapserv.utah.gov.Controllers { [Route("api/[controller]")] + [ApiExplorerSettings(IgnoreApi = true)] public class ValuesController : Controller { // GET api/values diff --git a/api.mapserv.utah.gov/Extensions/CandidateExtensionx.cs b/api.mapserv.utah.gov/Extensions/CandidateExtension.cs similarity index 100% rename from api.mapserv.utah.gov/Extensions/CandidateExtensionx.cs rename to api.mapserv.utah.gov/Extensions/CandidateExtension.cs diff --git a/api.mapserv.utah.gov/Models/RequestOptions/GeocodingOptions.cs b/api.mapserv.utah.gov/Models/RequestOptions/GeocodingOptions.cs index 853b8239..c4157781 100644 --- a/api.mapserv.utah.gov/Models/RequestOptions/GeocodingOptions.cs +++ b/api.mapserv.utah.gov/Models/RequestOptions/GeocodingOptions.cs @@ -1,59 +1,48 @@ -using api.mapserv.utah.gov.Models.Constants; +using System.ComponentModel; +using api.mapserv.utah.gov.Models.Constants; namespace api.mapserv.utah.gov.Models.RequestOptions { /// /// The options available for geocoding /// - public class GeocodingOptions : OptionBase + public class GeocodingOptions : ProjectableOptions { /// - /// Gets or sets the accept score for the address. + /// A score from 0 to 100 used to rank geocode candidates. + /// Default: 70 /// - /// - /// The accept score defaults to 70 in the GeocodeOptionsModelBinder. - /// + [DefaultValue(70)] public int AcceptScore { get; set; } = 70; /// - /// Gets or sets the suggest count for how many address candidates to return. + /// The count of candidates to return beside the highest match candidate. + /// Default: 0 /// - /// - /// The suggest count. - /// + [DefaultValue(0)] public int Suggest { get; set; } = 0; /// - /// Gets or sets the locators. + /// How the service will attempt to locate the address. + /// All is a combination of address point locators and road centerline locators; This will offer the best results. + /// addressPoints will only geocode on address points and roadCenterlines will only geocode on road centerlines. + /// Default: All. /// - /// - /// The locators to grab for geocoding. - /// + [DefaultValue(LocatorType.All)] public LocatorType Locators { get; set; } = LocatorType.All; /// - /// Gets or sets the spatial reference well known id. + /// How the service will handle P.O. Boxes. True will return the coordinates of the post office where the mail is delivered. False will return no match. P.O. Boxes can only be processed if the zone is a zip code. If a place name is used in the zone the geocode will return no match. + /// Default: true. /// - /// - /// The wkid. - /// - public int SpatialReference { get; set; } = 26912; - - /// - /// Instructs the API to try to find the post office or delivery point for a post office address. - /// - /// - /// true if should geocode po box; otherwise, false. - /// + [DefaultValue(true)] public bool PoBox { get; set; } = true; /// - /// Instructs the api to return the difference between the match address and the next best option. - /// This is only calculated if this property is true and the suggest count is 0 + /// Request the api to calculate the difference in score between the match address and the top suggestion. This flag is only calculated and returned when suggest=0 and there is a top suggestion. If there is no top suggestion, the property is not sent. If the value is 0, then you have a tie and should investigate the addresses by using the suggest items. + /// Default: false. /// - /// - /// true if should calculate the sccore difference; otherwise, false. - /// + [DefaultValue(false)] public bool ScoreDifference { get; set; } = false; public override string ToString() => $"AcceptScore: {AcceptScore}, SuggestCount: {Suggest}, JsonFormat: {Format}, Type: {Locators}, wkid: {SpatialReference} "; diff --git a/api.mapserv.utah.gov/Models/RequestOptions/OptionBase.cs b/api.mapserv.utah.gov/Models/RequestOptions/OptionBase.cs index 7df50f6b..26e04abd 100644 --- a/api.mapserv.utah.gov/Models/RequestOptions/OptionBase.cs +++ b/api.mapserv.utah.gov/Models/RequestOptions/OptionBase.cs @@ -1,20 +1,19 @@ -using api.mapserv.utah.gov.Models.Constants; +using System.ComponentModel; +using api.mapserv.utah.gov.Models.Constants; namespace api.mapserv.utah.gov.Models.RequestOptions { - public class OptionBase - { - public OptionBase() - { - Format = JsonFormat.None; - } + public class OptionBase + { + public OptionBase() + { + Format = JsonFormat.None; + } - /// - /// Gets or sets the json format for the geometry response. - /// - /// - /// The json format. - /// - public JsonFormat Format { get; set; } - } + /// + /// The format of the resulting address. esri json will easily parse into an esri.Graphic for display on a map and geojson will easily parse into a feature for use in many open source projects. If this value is omitted, the default json will be returned. + /// + [DefaultValue(JsonFormat.None)] + public JsonFormat Format { get; set; } + } } diff --git a/api.mapserv.utah.gov/Models/RequestOptions/ProjectableOptions.cs b/api.mapserv.utah.gov/Models/RequestOptions/ProjectableOptions.cs new file mode 100644 index 00000000..9b59e463 --- /dev/null +++ b/api.mapserv.utah.gov/Models/RequestOptions/ProjectableOptions.cs @@ -0,0 +1,17 @@ +using System; +using System.ComponentModel; + +namespace api.mapserv.utah.gov.Models.RequestOptions +{ + public class ProjectableOptions : OptionBase + { + /// + /// The spatial reference for the output and input geometries. + /// Choose any of the wkid's from the Geographic Coordinate System wkid reference or Projected Coordinate System wkid reference. + /// Default: 26912 + /// + [DefaultValue(26912)] + public int SpatialReference { get; set; } = 26912; + + } +} diff --git a/api.mapserv.utah.gov/Models/RequestOptions/ReverseGeocodingOptions.cs b/api.mapserv.utah.gov/Models/RequestOptions/ReverseGeocodingOptions.cs index 3808788a..f1b61212 100644 --- a/api.mapserv.utah.gov/Models/RequestOptions/ReverseGeocodingOptions.cs +++ b/api.mapserv.utah.gov/Models/RequestOptions/ReverseGeocodingOptions.cs @@ -1,21 +1,14 @@ -namespace api.mapserv.utah.gov.Models.RequestOptions +using System.ComponentModel; + +namespace api.mapserv.utah.gov.Models.RequestOptions { - public class ReverseGeocodingOptions : OptionBase + public class ReverseGeocodingOptions : ProjectableOptions { /// - /// Gets or sets the distance in meters from the point to find an address. + /// The distance in meters from the input location to look for an address. + /// Default: 5 /// - /// - /// The distance in meters. - /// + [DefaultValue(5)] public double Distance { get; set; } = 5; - - /// - /// Gets or sets the spatial reference well known id for the input coordinates. - /// - /// - /// The wkid. - /// - public int SpatialReference { get; set; } = 26912; } } diff --git a/api.mapserv.utah.gov/Startup.cs b/api.mapserv.utah.gov/Startup.cs index e3375a29..bce8b3e2 100644 --- a/api.mapserv.utah.gov/Startup.cs +++ b/api.mapserv.utah.gov/Startup.cs @@ -1,4 +1,7 @@ -using api.mapserv.utah.gov.Extensions; +using System; +using System.IO; +using System.Reflection; +using api.mapserv.utah.gov.Extensions; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.AspNetCore.Mvc; @@ -6,6 +9,7 @@ using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; using Newtonsoft.Json; +using Swashbuckle.AspNetCore.Swagger; using WebApiContrib.Core.Formatter.Jsonp; namespace api.mapserv.utah.gov @@ -28,7 +32,8 @@ public Startup(IConfiguration configuration, IHostingEnvironment env, ILoggerFac public void ConfigureServices(IServiceCollection services) { services.AddCors(); - services.AddMvc(options => { + services.AddMvc(options => + { options.AddApiResponseFormatters(); options.AddJsonpOutputFormatter(); }) @@ -45,6 +50,37 @@ public void ConfigureServices(IServiceCollection services) services.UseOptions(Configuration); services.UseDi(); + + services.AddSwaggerGen(c => + { + c.EnableAnnotations(); + c.DescribeAllParametersInCamelCase(); + c.DescribeAllEnumsAsStrings(); + c.DescribeStringEnumsInCamelCase(); + + c.SwaggerDoc("v1", new Info + { + Version = "v1", + Title = "AGRC WebAPI : OpenAPI Documentation", + Description = "OpenAPI Documentation", + Contact = new Contact + { + Name = "AGRC", + Email = string.Empty, + Url = "https://github.com/agrc/api.mapserv.utah.gov" + }, + License = new License + { + Name = "MIT", + Url = "https://github.com/agrc/api.mapserv.utah.gov/blob/master/LICENSE" + } + }); + + var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; + var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); + + c.IncludeXmlComments(xmlPath); + }); } // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. @@ -55,6 +91,20 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env) app.UseDeveloperExceptionPage(); } + app.UseSwagger(c => { + c.RouteTemplate = "openapi/{documentName}/api.json"; + }); + + app.UseSwaggerUI(c => + { + c.DocumentTitle = "AGRC WebAPI OpenAPI Documentation"; + c.RoutePrefix = "openapi"; + c.SwaggerEndpoint("/openapi/v1/api.json", "v1"); + c.SupportedSubmitMethods(new SubmitMethod[] {}); + c.EnableDeepLinking(); + c.DocExpansion(DocExpansion.List); + }); + app.UseMvc(); } } diff --git a/api.mapserv.utah.gov/api.mapserv.utah.gov.csproj b/api.mapserv.utah.gov/api.mapserv.utah.gov.csproj index 51f74d61..08050c5d 100644 --- a/api.mapserv.utah.gov/api.mapserv.utah.gov.csproj +++ b/api.mapserv.utah.gov/api.mapserv.utah.gov.csproj @@ -11,6 +11,10 @@ Latest + + true + $(NoWarn);1591 + @@ -29,6 +33,8 @@ + +