chore: api doc

Author: ychung-mot

server/StrDss.Api/ConfigureSwaggerOptions.cs

@@ -0,0 +1,42 @@
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace StrDss.Api
+{
+    public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConfigureSwaggerOptions"/> class.
+        /// </summary>
+        /// <param name="options">The options specified by <see cref="SwaggerGenOptions"/> object</param>
+        /// <inheritdoc />
+        public void Configure(SwaggerGenOptions options)
+        {
+
+            // Create Swagger documents per version and consumer
+            options.SwaggerDoc(Common.ApiTags.Default, CreateInfoForApiVersion(Common.ApiTags.Default, "StrData"));
+            options.SwaggerDoc(Common.ApiTags.Aps, CreateInfoForApiVersion(Common.ApiTags.Aps, $"StrData {Common.ApiTags.Aps}"));
+
+            // Include all paths
+            options.DocInclusionPredicate((name, api) => true);
+
+            // Filter endpoints based on consumer
+            options.DocumentFilter<SwaggerDocumentFilter>();
+
+            // Take first description on any conflict
+            options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
+        }
+
+        static OpenApiInfo CreateInfoForApiVersion(string version, string title)
+        {
+            var info = new OpenApiInfo()
+            {
+                Title = title,
+                Version = version
+            };
+
+            return info;
+        }
+    }
+}

server/StrDss.Api/Controllers/OrganizationsController.cs

@@ -6,6 +6,7 @@
 using StrDss.Model;
 using StrDss.Model.OrganizationDtos;
 using StrDss.Service;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace StrDss.Api.Controllers
 {
@@ -44,7 +45,15 @@ public async Task<ActionResult<List<DropdownNumDto>>> GetOrganizationsDropdown(s
             return Ok(await _orgService.GetOrganizationsDropdownAsync(type));
         }
 
-        [ApiAuthorize]
+        /// <summary>
+        /// Retrieves the Short-Term Rental (STR) requirements for a specified location based on longitude and latitude coordinates.
+        /// Validates the geographical boundaries of the input values to ensure they fall within acceptable ranges.
+        /// </summary>
+        /// <param name="longitude">The longitude of the location, must be between -180 and 180 degrees.</param>
+        /// <param name="latitude">The latitude of the location, must be between -90 and 90 degrees.</param>
+        /// <returns>An object containing STR requirements for the given location, or a validation error if the input is invalid.</returns>
+        [ApiAuthorize] //todo: specify permission
+        [SwaggerOperation(Tags = new string[] { Common.ApiTags.Aps })]
         [HttpGet("strrequirements", Name = "GetStrRequirements")]
         public async Task<ActionResult<StrRequirementsDto>> GetStrRequirements(double longitude, double latitude)
         {

server/StrDss.Api/Program.cs

@@ -18,7 +18,9 @@
 using StrDss.Service.Bceid;
 using Npgsql;
 using Serilog;
-using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Options;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using StrDss.Common;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -158,7 +160,15 @@
 
 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen();
+builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
+builder.Services.AddSwaggerGen(options =>
+{
+    options.EnableAnnotations();
+    options.UseAllOfToExtendReferenceSchemas();
+    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+    options.IncludeXmlComments(xmlPath);
+});
 
 var healthCheck = new HealthCheck(connString);
 builder.Services.AddHealthChecks().AddCheck("DbConnection", healthCheck);
@@ -168,8 +178,18 @@
 // Configure the HTTP request pipeline.
 if (app.Environment.IsDevelopment())
 {
-    app.UseSwagger();
-    app.UseSwaggerUI();
+    app.UseSwagger(option =>
+    {
+        option.RouteTemplate = "api/swagger/{documentName}/swagger.json";
+    });
+
+    app.UseSwaggerUI(option =>
+    {
+        option.SwaggerEndpoint($"/api/swagger/{ApiTags.Default}/swagger.json", ApiTags.Default);
+        option.SwaggerEndpoint($"/api/swagger/{ApiTags.Aps}/swagger.json", ApiTags.Aps);
+
+        option.RoutePrefix = "api/swagger";
+    });
 }
 
 app.UseHealthChecks("/healthz");

server/StrDss.Api/StrDss.Api.csproj

@@ -4,6 +4,7 @@
 		<TargetFramework>net7.0</TargetFramework>
 		<Nullable>enable</Nullable>
 		<ImplicitUsings>enable</ImplicitUsings>
+		<GenerateDocumentationFile>True</GenerateDocumentationFile>
 	</PropertyGroup>
 
 	<ItemGroup>
@@ -19,6 +20,7 @@
 		<PackageReference Include="Serilog.AspNetCore" Version="7.0.0" />
 		<PackageReference Include="Serilog.Extensions.Logging" Version="7.0.0" />
 		<PackageReference Include="Serilog.Sinks.File" Version="5.0.0" />
+		<PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.7.3" />
 	</ItemGroup>
 
 	<ItemGroup>

server/StrDss.Api/SwaggerDocumentFilter.cs

@@ -0,0 +1,41 @@
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace StrDss.Api
+{
+    public class SwaggerDocumentFilter : IDocumentFilter
+    {
+        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
+        {
+            // Key is read-only so make a copy of the Paths property
+            var pathsPerConsumer = new OpenApiPaths();
+            var referencedSchemas = new HashSet<string>();
+
+            if (swaggerDoc.Info.Version == Common.ApiTags.Aps)
+            {
+                foreach (var path in swaggerDoc.Paths)
+                {
+                    // If there are any tags (all methods are decorated with "SwaggerOperation(Tags = new[]...") with the current consumer name
+                    var p = path.Value?.Operations?.Values?.FirstOrDefault();
+                    if (p != null && p.Tags
+                            .Where(t => Common.ApiTags.ApsTagList.Contains(t.Name)).Any())
+                    {
+                        // Add the path to the collection of paths for current consumer
+                        pathsPerConsumer.Add(path.Key, path.Value);
+                    }
+                }
+
+
+            }
+            else
+            {
+                foreach (var path in swaggerDoc.Paths)
+                {
+                    if (path.Key != null && path.Value != null) pathsPerConsumer.Add(path.Key, path.Value);
+                }
+            }
+
+            swaggerDoc.Paths = pathsPerConsumer;
+        }
+    }
+}

server/StrDss.Common/Constants.cs

@@ -356,4 +356,11 @@ public static class ListingExportFileNames
         public const string All = "BC";
         public const string AllPr = "BC_PR";
     }
+
+    public static class ApiTags
+    {
+        public const string Default = "stadata";
+        public const string Aps = "aps";
+        public static readonly string[] ApsTagList = { "aps" };
+    }
 }

server/StrDss.Data/Repositories/OrganizationRepository.cs

@@ -140,7 +140,7 @@ FROM dss_organization
                     OrganizationNm = o.OrganizationNm,
                     IsPrincipalResidenceRequired = o.IsPrincipalResidenceRequired,
                     IsBusinessLicenceRequired = o.IsBusinessLicenceRequired,
-                    IsStrProhibited = null
+                    IsStrProhibited = null //todo: map with the new column
                 })
                 .OrderBy(o => o.OrganizationNm)
                 .FirstOrDefaultAsync();