Initial Support for OpenAPI v3.0.1 description document creation

src/Config/DataApiBuilderException.cs

@@ -79,7 +79,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>
+            /// Attempting to generate OpenAPI document failed.
+            /// </summary>
+            OpenApiDocumentGenerationFailure,
+            /// <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/Azure.DataApiBuilder.Service.csproj

@@ -60,6 +60,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" />
@@ -69,6 +70,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/Controllers/OpenApiController.cs

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using Azure.DataApiBuilder.Service.Exceptions;
+using Azure.DataApiBuilder.Service.Services;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Azure.DataApiBuilder.Service.Controllers
+{
+    /// <summary>
+    /// 
+    /// </summary>
+    [Route("[controller]")]
+    [ApiController]
+    public class OpenApiController : ControllerBase
+    {
+        private IOpenApiDocumentor _apiDocumentor;
+
+        public OpenApiController(IOpenApiDocumentor openApiDocumentor)
+        {
+            _apiDocumentor = openApiDocumentor;
+        }
+
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <returns></returns>
+        [HttpGet]
+        public IActionResult Get()
+        {
+            return _apiDocumentor.TryGetDocument(out string? document) ? Ok(document) : NotFound();
+        }
+
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <returns></returns>
+        [HttpPost]
+        public IActionResult Post()
+        {
+            try
+            {
+                _apiDocumentor.CreateDocument();
+
+                if (_apiDocumentor.TryGetDocument(out string? document))
+                {
+                    return new CreatedResult(location:"/openapi" ,value: document);
+                }
+
+                return NotFound();
+            }
+            catch (DataApiBuilderException dabException)
+            {
+                Response.StatusCode = (int)dabException.StatusCode;
+                return new JsonResult(new
+                {
+                    error = new
+                    {
+                        code = dabException.SubStatusCode.ToString(),
+                        message = dabException.Message,
+                        status = (int)dabException.StatusCode
+                    }
+                });
+            }
+        }
+    }
+}

src/Service/Services/IOpenApiDocumentor.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Azure.DataApiBuilder.Service.Services
+{
+    public interface IOpenApiDocumentor
+    {
+        public bool TryGetDocument([NotNullWhen(true)] out string? document);
+        public void CreateDocument();
+    }
+}