Initial Support for OpenAPI v3.0.1 description document creation (#1462)

## Why make this change?

- Closes #916 by adding support for creating an OpenAPI description
document for the Data API builder REST endpoint.
https://spec.openapis.org/oas/v3.0.3

## What is this change?

- Uses Microsoft/OpenAPI.NET to generate an OpenAPI description document
for entities defined in the runtime config which are used for the REST
endpoint.

## How was this tested?

- [x] Integration Tests
- [ ] Unit Tests

## Sample Request(s)

- https://localhost:5001/swagger -> Swagger UI visualization of
generated document.
- https://localhost:5001/openapi -> 
  - [GET] Download/View Generated document

Author: seantleonard

src/Config/DataApiBuilderException.cs

@@ -85,7 +85,19 @@ public enum SubStatusCodes
             /// <summary>
             /// Error encountered while doing data type conversions.
             /// </summary>
-            ErrorProcessingData
+            ErrorProcessingData,
+            /// <summary>
+            /// Attempting to generate OpenAPI document when one already exists.
+            /// </summary>
+            OpenApiDocumentAlreadyExists,
+            /// <summary>
+            /// Attempt to create OpenAPI document failed.
+            /// </summary>
+            OpenApiDocumentCreationFailure,
+            /// <summary>
+            /// Global REST endpoint disabled in runtime configuration.
+            /// </summary>
+            GlobalRestEndpointDisabled
         }
 
         public HttpStatusCode StatusCode { get; }

src/Directory.Packages.props

@@ -17,13 +17,14 @@
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="6.0.14" />
     <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="6.0.14" />
     <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.20.0" />
-      <!--When updating Microsoft.Data.SqlClient, update license URL in scripts/notice-generation.ps1-->
+    <!--When updating Microsoft.Data.SqlClient, update license URL in scripts/notice-generation.ps1-->
     <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.3.2" />
     <PackageVersion Include="Microsoft.OData.Edm" Version="7.12.5" />
     <PackageVersion Include="Microsoft.OData.Core" Version="7.12.5" />
+    <PackageVersion Include="Microsoft.OpenApi" Version="1.6.3" />
     <PackageVersion Include="Moq" Version="4.18.2" />
     <PackageVersion Include="MSTest.TestAdapter" Version="2.2.10" />
     <PackageVersion Include="MSTest.TestFramework" Version="2.2.10" />
@@ -32,6 +33,7 @@
     <PackageVersion Include="Npgsql" Version="7.0.1" />
     <PackageVersion Include="Polly" Version="7.2.3" />
     <PackageVersion Include="StyleCop.Analyzers" Version="1.1.118" />
+    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.5.0" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
     <PackageVersion Include="System.Drawing.Common" Version="6.0.0" />
     <PackageVersion Include="System.IO.Abstractions" Version="17.2.3" />

src/Service.Tests/Configuration/ConfigurationTests.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Azure.DataApiBuilder.Service.Tests
+{
+    public class OpenApiDocumentorConstants
+    {
+        public const string TOPLEVELPROPERTY_OPENAPI = "openapi";
+        public const string TOPLEVELPROPERTY_INFO = "info";
+        public const string TOPLEVELPROPERTY_SERVERS = "servers";
+        public const string TOPLEVELPROPERTY_PATHS = "paths";
+        public const string TOPLEVELPROPERTY_COMPONENTS = "components";
+        public const string PROPERTY_SCHEMAS = "schemas";
+    }
+}

src/Service.Tests/OpenApiDocumentor/OpenApiDocumentorConstants.cs

@@ -27,9 +27,9 @@ public class RestServiceUnitTests
         #region Positive Cases
 
         /// <summary>
-        /// Test the REST Service for parsing entity name
-        /// and primary key route from the route, given a
-        /// particular path.
+        /// Validates that the RestService helper function GetEntityNameAndPrimaryKeyRouteFromRoute
+        /// properly parses the entity name and primary key route from the route,
+        /// given the input path (which does not include the path base).
         /// </summary>
         /// <param name="route">The route to parse.</param>
         /// <param name="path">The path that the route starts with.</param>
@@ -42,14 +42,16 @@ public class RestServiceUnitTests
         [DataRow("rest api/Book/id/1", "/rest api", "Book", "id/1")]
         [DataRow(" rest_api/commodities/categoryid/1/pieceid/1", "/ rest_api", "commodities", "categoryid/1/pieceid/1")]
         [DataRow("rest-api/Book/id/1", "/rest-api", "Book", "id/1")]
-        public void ParseEntityNameAndPrimaryKeyTest(string route,
-                                                     string path,
-                                                     string expectedEntityName,
-                                                     string expectedPrimaryKeyRoute)
+        public void ParseEntityNameAndPrimaryKeyTest(
+            string route,
+            string path,
+            string expectedEntityName,
+            string expectedPrimaryKeyRoute)
         {
             InitializeTest(path, expectedEntityName);
+            string routeAfterPathBase = _restService.GetRouteAfterPathBase(route);
             (string actualEntityName, string actualPrimaryKeyRoute) =
-                _restService.GetEntityNameAndPrimaryKeyRouteFromRoute(route);
+                _restService.GetEntityNameAndPrimaryKeyRouteFromRoute(routeAfterPathBase);
             Assert.AreEqual(expectedEntityName, actualEntityName);
             Assert.AreEqual(expectedPrimaryKeyRoute, actualPrimaryKeyRoute);
         }
@@ -76,8 +78,7 @@ public void ErrorForInvalidRouteAndPathToParseTest(string route,
             InitializeTest(path, route);
             try
             {
-                (string actualEntityName, string actualPrimaryKeyRoute) =
-                _restService.GetEntityNameAndPrimaryKeyRouteFromRoute(route);
+                string routeAfterPathBase = _restService.GetRouteAfterPathBase(route);
             }
             catch (DataApiBuilderException e)
             {

src/Service.Tests/Unittests/RestServiceUnitTests.cs

@@ -58,6 +58,7 @@
         <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
         <PackageReference Include="Microsoft.OData.Edm" />
         <PackageReference Include="Microsoft.OData.Core" />
+        <PackageReference Include="Microsoft.OpenApi" />
         <PackageReference Include="MSTest.TestFramework" />
         <PackageReference Include="MySqlConnector" />
         <PackageReference Include="Newtonsoft.Json" />
@@ -67,6 +68,7 @@
             <PrivateAssets>all</PrivateAssets>
             <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
         </PackageReference>
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" />
         <PackageReference Include="System.CommandLine" />
         <PackageReference Include="System.IO.Abstractions" />
         <PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="All"/>

src/Service/Azure.DataApiBuilder.Service.csproj

@@ -3,10 +3,12 @@
 
 using System;
 using System.Net;
+using System.Net.Mime;
 using System.Threading.Tasks;
 using Azure.DataApiBuilder.Service.Exceptions;
 using Azure.DataApiBuilder.Service.Models;
 using Azure.DataApiBuilder.Service.Services;
+using Azure.DataApiBuilder.Service.Services.OpenAPI;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Http.Extensions;
 using Microsoft.AspNetCore.Mvc;
@@ -27,6 +29,11 @@ public class RestController : ControllerBase
         /// Service providing REST Api executions.
         /// </summary>
         private readonly RestService _restService;
+
+        /// <summary>
+        /// OpenAPI description document creation service.
+        /// </summary>
+        private readonly IOpenApiDocumentor _openApiDocumentor;
         /// <summary>
         /// String representing the value associated with "code" for a server error
         /// </summary>
@@ -44,9 +51,10 @@ public class RestController : ControllerBase
         /// <summary>
         /// Constructor.
         /// </summary>
-        public RestController(RestService restService, ILogger<RestController> logger)
+        public RestController(RestService restService, IOpenApiDocumentor openApiDocumentor, ILogger<RestController> logger)
         {
             _restService = restService;
+            _openApiDocumentor = openApiDocumentor;
             _logger = logger;
         }
 
@@ -87,8 +95,8 @@ public async Task<IActionResult> Find(
             string route)
         {
             return await HandleOperation(
-                route,
-                Config.Operation.Read);
+            route,
+            Config.Operation.Read);
         }
 
         /// <summary>
@@ -188,7 +196,21 @@ private async Task<IActionResult> HandleOperation(
                         subStatusCode: DataApiBuilderException.SubStatusCodes.BadRequest);
                 }
 
-                (string entityName, string primaryKeyRoute) = _restService.GetEntityNameAndPrimaryKeyRouteFromRoute(route);
+                // Validate the PathBase matches the configured REST path.
+                string routeAfterPathBase = _restService.GetRouteAfterPathBase(route);
+
+                // Explicitly handle OpenAPI description document retrieval requests.
+                if (string.Equals(routeAfterPathBase, OpenApiDocumentor.OPENAPI_ROUTE, StringComparison.OrdinalIgnoreCase))
+                {
+                    if (_openApiDocumentor.TryGetDocument(out string? document))
+                    {
+                        return Content(document, MediaTypeNames.Application.Json);
+                    }
+
+                    return NotFound();
+                }
+
+                (string entityName, string primaryKeyRoute) = _restService.GetEntityNameAndPrimaryKeyRouteFromRoute(routeAfterPathBase);
 
                 IActionResult? result = await _restService.ExecuteAsync(entityName, operationType, primaryKeyRoute);
 

src/Service/Controllers/RestController.cs

@@ -317,7 +317,7 @@ private async Task FillSchemaForStoredProcedureAsync(
                     new()
                     {
                         SystemType = systemType,
-                        DbType = DbTypeHelper.GetDbTypeFromSystemType(systemType)
+                        DbType = TypeHelper.GetDbTypeFromSystemType(systemType)
                     }
                 );
             }
@@ -1016,7 +1016,7 @@ private async Task PopulateSourceDefinitionAsync(
                     IsNullable = (bool)columnInfoFromAdapter["AllowDBNull"],
                     IsAutoGenerated = (bool)columnInfoFromAdapter["IsAutoIncrement"],
                     SystemType = systemTypeOfColumn,
-                    DbType = DbTypeHelper.GetDbTypeFromSystemType(systemTypeOfColumn)
+                    DbType = TypeHelper.GetDbTypeFromSystemType(systemTypeOfColumn)
                 };
 
                 // Tests may try to add the same column simultaneously

src/Service/Services/DbTypeHelper.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Azure.DataApiBuilder.Service.Services.OpenAPI
+{
+    /// <summary>
+    /// Interface for the service which generates and provides the OpenAPI description document
+    /// describing the DAB engine's entity REST endpoint paths.
+    /// </summary>
+    public interface IOpenApiDocumentor
+    {
+        /// <summary>
+        /// Attempts to return the OpenAPI description document, if generated.
+        /// </summary>
+        /// <param name="document">String representation of JSON OpenAPI description document.</param>
+        /// <returns>True (plus string representation of document), when document exists. False, otherwise.</returns>
+        public bool TryGetDocument([NotNullWhen(true)] out string? document);
+
+        /// <summary>
+        /// Creates an OpenAPI description document using OpenAPI.NET.
+        /// Document compliant with patches of OpenAPI V3.0 spec 3.0.0 and 3.0.1,
+        /// aligned with specification support provided by Microsoft.OpenApi.
+        /// </summary>
+        /// <exception cref="DataApiBuilderException">Raised when document is already generated
+        /// or a failure occurs during generation.</exception>
+        /// <seealso cref="https://github.com/microsoft/OpenAPI.NET/blob/1.6.3/src/Microsoft.OpenApi/OpenApiSpecVersion.cs"/>
+        public void CreateDocument();
+    }
+}