v5.13.0 (#249)

* Adding `dotnet run openapi` option.

* Finalize changes for release.

CHANGELOG.md

@@ -2,20 +2,29 @@
 
 Represents the **NuGet** versions.
 
+## v5.13.0
+- *Enhancement:* Added `dotnet run openapi` option to perform *basic* parsing of an [OpenAPI](https://spec.openapis.org/oas/latest.html) document generating the corresponding `Entity`, `Operation` and `Property` configuration into a temporary YAML file. The contents are expected to then be copied and pasted into the appropriate YAML destination and further configured as necessary.
+  - Execute `dotnet run -- --help` to see all command-line capabilities for this.
+  - All OpenAPI paths (operations) are generated into a single `Service` entity; this can be further split into multiple entities manually as required.
+  - Where a schema (entity) is specified more than once with the same name it will attempt to match the configuration (including properties) to an existing entity and reuse; otherwise, a new entity will be created with a postfix number to ensure uniqueness.
+  - The `OpenApiArgs` supports further options to enable additional customization of processing and generated output; this is set using the `CodeGenConsole.WithOpenApiArgs` method. 
+  - _Note:_ this is in _preview_ until explicitly noted in a later version; as such, the generated YAML will require manual review and adjustment as required and may not support all features (for some time or ever). This is only intended to help accelerate the initial configuration process where an OpenAPI document is available.
+- *Fixed*: Sanitize the generated `Api.Controller` and `Common` summary text comments to remove internal references, etc.
+
 ## v5.12.9
 - *Fixed:* Enable `text` specification to be used as-is by prefixing with a `+` plus-sign character. 
 - *Fixed:* Upgraded `DbEx` (`v2.5.8`) to include all related fixes and improvements.
 
 ## v5.12.8
-- *Fixed*: Fixed the model code-generation by allowing the `ModelInherits` to be specified within the `Entity` YAML configuration to override the default.
-- *Fixed*: Fixed `dotnet run count` to exclude paths that start with `.` (dot) to avoid including hidden files in the count.
+- *Fixed:* Fixed the model code-generation by allowing the `ModelInherits` to be specified within the `Entity` YAML configuration to override the default.
+- *Fixed:* Fixed `dotnet run count` to exclude paths that start with `.` (dot) to avoid including hidden files in the count.
 
 ## v5.12.7
-- *Fixed*: Fixes the model code-generation to auto implement the `ITenantId` and `ILogicallyDeleted` where corresponding properties are defined.
-- *Fixed*: Fixed the manager code-generation to output the `IdentifierGenerator` code where inheriting the `Id` property.
+- *Fixed:* Fixes the model code-generation to auto implement the `ITenantId` and `ILogicallyDeleted` where corresponding properties are defined.
+- *Fixed:* Fixed the manager code-generation to output the `IdentifierGenerator` code where inheriting the `Id` property.
 
 ## v5.12.6
-- *Fixed*: The EF Model generation has had the `ITenantId.TenantId` filtering removed as out-of-the-box EF caches first and uses resulting in an unexpected side-effect. The `CoreEx.EntityFramework` as of `v3.20.0` automatically includes tenant filtering to achieve the desired behavior.
+- *Fixed:* The EF Model generation has had the `ITenantId.TenantId` filtering removed as out-of-the-box EF caches first and uses resulting in an unexpected side-effect. The `CoreEx.EntityFramework` as of `v3.20.0` automatically includes tenant filtering to achieve the desired behavior.
 - *Fixed:* Upgraded `CoreEx` (`v3.20.0`) to include all related fixes and improvements.
 
 ## v5.12.5

Common.targets

@@ -1,6 +1,6 @@
 <Project>
 	<PropertyGroup>
-		<Version>5.12.9</Version>
+		<Version>5.13.0</Version>
 		<LangVersion>preview</LangVersion>
 		<Authors>Avanade</Authors>
 		<Company>Avanade</Company>
@@ -27,6 +27,7 @@
     <IsPackable>true</IsPackable>
 		<GenerateDocumentationFile>true</GenerateDocumentationFile>
 		<GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
+    <LangVersion>preview</LangVersion>
 	</PropertyGroup>
 
 	<ItemGroup>

docs/Entity-Entity-Config.md

@@ -215,7 +215,7 @@ Property | Description
 **`databaseName`** | The .NET database interface name (used where `AutoImplement` is `Database`).<br/>&dagger; Defaults to the `CodeGeneration.DatabaseName` configuration property (its default value is `IDatabase`).
 **`databaseSchema`** | The database schema name (used where `AutoImplement` is `Database`).<br/>&dagger; Defaults to `dbo`.
 `databaseMapperInheritsFrom` | The name of the `Mapper` that the generated Database `Mapper` inherits from.
-`databaseCustomerMapper` | Indicates that a custom Database `Mapper` will be used; i.e. not generated.<br/>&dagger; Otherwise, by default, a `Mapper` will be generated.
+`databaseCustomMapper` | Indicates that a custom Database `Mapper` will be used; i.e. not generated.<br/>&dagger; Otherwise, by default, a `Mapper` will be generated.
 `databaseMapperEx` | Indicates that a `DatabaseMapperEx` (extended/explicit) will be used; versus, `DatabaseMapper` (which uses Reflection internally).<br/>&dagger; Defaults to `CodeGeneration.DatabaseMapperEx` (its default value is `true`). The `DatabaseMapperEx` essentially replaces the `DatabaseMapper` as it is more performant; this option can be used where leagcy/existing behavior is required.
 
 <br/>

samples/Cdr.Banking/Cdr.Banking.Api/Cdr.Banking.Api.csproj

@@ -5,7 +5,7 @@
     <ImplicitUsings>true</ImplicitUsings>
   </PropertyGroup>
   <ItemGroup>
-    <PackageReference Include="CoreEx.AspNetCore" Version="3.21.0" />
+    <PackageReference Include="CoreEx.AspNetCore" Version="3.21.1" />
     <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="6.6.2" />
   </ItemGroup>
   <ItemGroup>

samples/Cdr.Banking/Cdr.Banking.Api/Controllers/Generated/AccountController.cs

@@ -28,10 +28,10 @@ public AccountController(WebApi webApi, IAccountManager manager)
     /// <summary>
     /// Get all accounts.
     /// </summary>
-    /// <param name="productCategory">The Product Category (see <see cref="RefDataNamespace.ProductCategory"/>).</param>
-    /// <param name="openStatus">The Open Status (see <see cref="RefDataNamespace.OpenStatus"/>).</param>
+    /// <param name="productCategory">The Product Category.</param>
+    /// <param name="openStatus">The Open Status.</param>
     /// <param name="isOwned">Indicates whether Is Owned.</param>
-    /// <returns>The <see cref="AccountCollection"/></returns>
+    /// <returns>The <c>Account</c> array</returns>
     [Tags("Banking", "Accounts")]
     [HttpGet("api/v1/banking/accounts", Name="Account_GetAccounts")]
     [Paging]
@@ -44,32 +44,32 @@ public Task<IActionResult> GetAccounts([FromQuery(Name="product-category")] stri
     }
 
     /// <summary>
-    /// Get <see cref="AccountDetail"/>.
+    /// Get <c>AccountDetail</c>.
     /// </summary>
-    /// <param name="accountId">The <see cref="Account"/> identifier.</param>
-    /// <returns>The selected <see cref="AccountDetail"/> where found.</returns>
+    /// <param name="accountId">The <c>Account</c> identifier.</param>
+    /// <returns>The selected <c>AccountDetail</c> where found.</returns>
     [HttpGet("api/v1/banking/accounts/{accountId}", Name="Account_GetDetail")]
     [ProducesResponseType(typeof(Common.Entities.AccountDetail), (int)HttpStatusCode.OK)]
     [ProducesResponseType((int)HttpStatusCode.NotFound)]
     public Task<IActionResult> GetDetail(string? accountId)
         => _webApi.GetWithResultAsync<AccountDetail?>(Request, p => _manager.GetDetailAsync(accountId));
 
     /// <summary>
-    /// Get <see cref="Account"/> <see cref="Balance"/>.
+    /// Get <c>Account</c> <c>Balance</c>.
     /// </summary>
-    /// <param name="accountId">The <see cref="Account"/> identifier.</param>
-    /// <returns>The selected <see cref="Balance"/> where found.</returns>
+    /// <param name="accountId">The <c>Account</c> identifier.</param>
+    /// <returns>The selected <c>Balance</c> where found.</returns>
     [HttpGet("api/v1/banking/accounts/{accountId}/balance", Name="Account_GetBalance")]
     [ProducesResponseType(typeof(Common.Entities.Balance), (int)HttpStatusCode.OK)]
     [ProducesResponseType((int)HttpStatusCode.NotFound)]
     public Task<IActionResult> GetBalance(string? accountId)
         => _webApi.GetWithResultAsync<Balance?>(Request, p => _manager.GetBalanceAsync(accountId));
 
     /// <summary>
-    /// Get <see cref="Account"/> statement (file).
+    /// Get <c>Account</c> statement (file).
     /// </summary>
-    /// <param name="accountId">The <see cref="Account"/> identifier.</param>
-    /// <returns>A resultant <see cref="FileContentResult"/>.</returns>
+    /// <param name="accountId">The <c>Account</c> identifier.</param>
+    /// <returns>A resultant <c>FileContentResult</c>.</returns>
     [HttpGet("api/v1/banking/accounts/{accountId}/statement", Name="Account_GetStatement")]
     [Produces("text/plain")]
     [ProducesResponseType((int)HttpStatusCode.OK)]

samples/Cdr.Banking/Cdr.Banking.Api/Controllers/Generated/ReferenceDataController.cs

@@ -25,66 +25,66 @@ public ReferenceDataController(ReferenceDataContentWebApi webApi, ReferenceDataO
         { _webApi = webApi.ThrowIfNull(); _orchestrator = orchestrator.ThrowIfNull(); }
 
     /// <summary> 
-    /// Gets all of the <see cref="RefDataNamespace.OpenStatus"/> reference data items that match the specified criteria.
+    /// Gets all of the 'OpenStatus' reference data items that match the specified criteria.
     /// </summary>
     /// <param name="codes">The reference data code list.</param>
     /// <param name="text">The reference data text (including wildcards).</param>
-    /// <returns>A RefDataNamespace.OpenStatus collection.</returns>
+    /// <returns>The 'OpenStatus' array.</returns>
     [HttpGet("api/v1/ref/openstatuses", Name="ReferenceData_OpenStatusGetAll")]
     [ProducesResponseType(typeof(IEnumerable<CommonRefDataNamespace.OpenStatus>), (int)HttpStatusCode.OK)]
     public Task<IActionResult> OpenStatusGetAll([FromQuery] IEnumerable<string>? codes = default, string? text = default)
         => _webApi.GetAsync(Request, p => _orchestrator.GetWithFilterAsync<RefDataNamespace.OpenStatus>(codes, text, p.RequestOptions.IncludeInactive));
 
     /// <summary> 
-    /// Gets all of the <see cref="RefDataNamespace.ProductCategory"/> reference data items that match the specified criteria.
+    /// Gets all of the 'ProductCategory' reference data items that match the specified criteria.
     /// </summary>
     /// <param name="codes">The reference data code list.</param>
     /// <param name="text">The reference data text (including wildcards).</param>
-    /// <returns>A RefDataNamespace.ProductCategory collection.</returns>
+    /// <returns>The 'ProductCategory' array.</returns>
     [HttpGet("api/v1/ref/productcategories", Name="ReferenceData_ProductCategoryGetAll")]
     [ProducesResponseType(typeof(IEnumerable<CommonRefDataNamespace.ProductCategory>), (int)HttpStatusCode.OK)]
     public Task<IActionResult> ProductCategoryGetAll([FromQuery] IEnumerable<string>? codes = default, string? text = default)
         => _webApi.GetAsync(Request, p => _orchestrator.GetWithFilterAsync<RefDataNamespace.ProductCategory>(codes, text, p.RequestOptions.IncludeInactive));
 
     /// <summary> 
-    /// Gets all of the <see cref="RefDataNamespace.AccountUType"/> reference data items that match the specified criteria.
+    /// Gets all of the 'AccountUType' reference data items that match the specified criteria.
     /// </summary>
     /// <param name="codes">The reference data code list.</param>
     /// <param name="text">The reference data text (including wildcards).</param>
-    /// <returns>A RefDataNamespace.AccountUType collection.</returns>
+    /// <returns>The 'AccountUType' array.</returns>
     [HttpGet("api/v1/ref/accountutypes", Name="ReferenceData_AccountUTypeGetAll")]
     [ProducesResponseType(typeof(IEnumerable<CommonRefDataNamespace.AccountUType>), (int)HttpStatusCode.OK)]
     public Task<IActionResult> AccountUTypeGetAll([FromQuery] IEnumerable<string>? codes = default, string? text = default)
         => _webApi.GetAsync(Request, p => _orchestrator.GetWithFilterAsync<RefDataNamespace.AccountUType>(codes, text, p.RequestOptions.IncludeInactive));
 
     /// <summary> 
-    /// Gets all of the <see cref="RefDataNamespace.MaturityInstructions"/> reference data items that match the specified criteria.
+    /// Gets all of the 'MaturityInstructions' reference data items that match the specified criteria.
     /// </summary>
     /// <param name="codes">The reference data code list.</param>
     /// <param name="text">The reference data text (including wildcards).</param>
-    /// <returns>A RefDataNamespace.MaturityInstructions collection.</returns>
+    /// <returns>The 'MaturityInstructions' array.</returns>
     [HttpGet("api/v1/ref/maturityinstructions", Name="ReferenceData_MaturityInstructionsGetAll")]
     [ProducesResponseType(typeof(IEnumerable<CommonRefDataNamespace.MaturityInstructions>), (int)HttpStatusCode.OK)]
     public Task<IActionResult> MaturityInstructionsGetAll([FromQuery] IEnumerable<string>? codes = default, string? text = default)
         => _webApi.GetAsync(Request, p => _orchestrator.GetWithFilterAsync<RefDataNamespace.MaturityInstructions>(codes, text, p.RequestOptions.IncludeInactive));
 
     /// <summary> 
-    /// Gets all of the <see cref="RefDataNamespace.TransactionType"/> reference data items that match the specified criteria.
+    /// Gets all of the 'TransactionType' reference data items that match the specified criteria.
     /// </summary>
     /// <param name="codes">The reference data code list.</param>
     /// <param name="text">The reference data text (including wildcards).</param>
-    /// <returns>A RefDataNamespace.TransactionType collection.</returns>
+    /// <returns>The 'TransactionType' array.</returns>
     [HttpGet("api/v1/ref/transactiontypes", Name="ReferenceData_TransactionTypeGetAll")]
     [ProducesResponseType(typeof(IEnumerable<CommonRefDataNamespace.TransactionType>), (int)HttpStatusCode.OK)]
     public Task<IActionResult> TransactionTypeGetAll([FromQuery] IEnumerable<string>? codes = default, string? text = default)
         => _webApi.GetAsync(Request, p => _orchestrator.GetWithFilterAsync<RefDataNamespace.TransactionType>(codes, text, p.RequestOptions.IncludeInactive));
 
     /// <summary> 
-    /// Gets all of the <see cref="RefDataNamespace.TransactionStatus"/> reference data items that match the specified criteria.
+    /// Gets all of the 'TransactionStatus' reference data items that match the specified criteria.
     /// </summary>
     /// <param name="codes">The reference data code list.</param>
     /// <param name="text">The reference data text (including wildcards).</param>
-    /// <returns>A RefDataNamespace.TransactionStatus collection.</returns>
+    /// <returns>The 'TransactionStatus' array.</returns>
     [HttpGet("api/v1/ref/transactionstatuses", Name="ReferenceData_TransactionStatusGetAll")]
     [ProducesResponseType(typeof(IEnumerable<CommonRefDataNamespace.TransactionStatus>), (int)HttpStatusCode.OK)]
     public Task<IActionResult> TransactionStatusGetAll([FromQuery] IEnumerable<string>? codes = default, string? text = default)
@@ -93,7 +93,7 @@ public Task<IActionResult> TransactionStatusGetAll([FromQuery] IEnumerable<strin
     /// <summary>
     /// Gets the reference data entries for the specified entities and codes from the query string; e.g: api/v1/ref?entity=codeX,codeY&amp;entity2=codeZ&amp;entity3
     /// </summary>
-    /// <returns>A <see cref="ReferenceDataMultiDictionary"/>.</returns>
+    /// <returns>The 'ReferenceDataMultiDictionary'.</returns>
     [HttpGet("api/v1/ref", Name="ReferenceData_GetNamed")]
     [ProducesResponseType(typeof(CoreEx.RefData.ReferenceDataMultiDictionary), (int)HttpStatusCode.OK)]
     public Task<IActionResult> GetNamed() => _webApi.GetAsync(Request, p => _orchestrator.GetNamedAsync(p.RequestOptions));

samples/Cdr.Banking/Cdr.Banking.Api/Controllers/Generated/TransactionController.cs

@@ -33,7 +33,7 @@ public TransactionController(WebApi webApi, ITransactionManager manager)
     /// <param name="minAmount">The Min Amount.</param>
     /// <param name="maxAmount">The Max Amount.</param>
     /// <param name="text">The Text.</param>
-    /// <returns>The <see cref="TransactionCollection"/></returns>
+    /// <returns>The <c>Transaction</c> array</returns>
     [HttpGet("api/v1/banking/accounts/{accountId}/transactions", Name="Transaction_GetTransactions")]
     [Paging]
     [ProducesResponseType(typeof(Common.Entities.TransactionCollection), (int)HttpStatusCode.OK)]

samples/Cdr.Banking/Cdr.Banking.Business/Cdr.Banking.Business.csproj

@@ -2,6 +2,7 @@
   <PropertyGroup>
     <TargetFramework>net6.0</TargetFramework>
     <Nullable>enable</Nullable>
+    <LangVersion>preview</LangVersion>
     <ImplicitUsings>true</ImplicitUsings>
   </PropertyGroup>
   <ItemGroup>
@@ -11,8 +12,8 @@
     <Folder Include="DataSvc\" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="CoreEx.AspNetCore" Version="3.21.0" />
-    <PackageReference Include="CoreEx.Cosmos" Version="3.21.0" />
-    <PackageReference Include="CoreEx.Validation" Version="3.21.0" />
+    <PackageReference Include="CoreEx.AspNetCore" Version="3.21.1" />
+    <PackageReference Include="CoreEx.Cosmos" Version="3.21.1" />
+    <PackageReference Include="CoreEx.Validation" Version="3.21.1" />
   </ItemGroup>
 </Project>

samples/Cdr.Banking/Cdr.Banking.Business/Generated/ReferenceDataProvider.cs

@@ -20,15 +20,15 @@ public partial class ReferenceDataProvider : IReferenceDataProvider
     partial void ReferenceDataProviderCtor(); // Enables the ReferenceDataProvider constructor to be extended.
 
     /// <inheritdoc/>
-    public Type[] Types => new Type[] 
-    {
+    public Type[] Types =>
+    [
         typeof(RefDataNamespace.OpenStatus),
         typeof(RefDataNamespace.ProductCategory),
         typeof(RefDataNamespace.AccountUType),
         typeof(RefDataNamespace.MaturityInstructions),
         typeof(RefDataNamespace.TransactionType),
         typeof(RefDataNamespace.TransactionStatus)
-    };
+    ];
 
     /// <inheritdoc/>
     public Task<Result<IReferenceDataCollection>> GetAsync(Type type, CancellationToken cancellationToken = default) => _dataService.GetAsync(type);

samples/Cdr.Banking/Cdr.Banking.CodeGen/Properties/launchSettings.json

@@ -2,7 +2,7 @@
   "profiles": {
     "Cdr.Banking.CodeGen": {
       "commandName": "Project",
-      "commandLineArgs": "endpoints"
+      "commandLineArgs": "entity"
     }
   }
 }

samples/Cdr.Banking/Cdr.Banking.Common/Cdr.Banking.Common.csproj

@@ -8,6 +8,6 @@
     <Folder Include="Entities\" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="CoreEx" Version="3.21.0" />
+    <PackageReference Include="CoreEx" Version="3.21.1" />
   </ItemGroup>
 </Project>

samples/Cdr.Banking/Cdr.Banking.Common/Entities/Generated/Account.cs

@@ -63,12 +63,12 @@ public partial class Account : IIdentifier<string>
     }
 
     /// <summary>
-    /// Represents the <see cref="Account"/> collection.
+    /// Represents the <c>Account</c> collection.
     /// </summary>
     public partial class AccountCollection : List<Account> { }
 
     /// <summary>
-    /// Represents the <see cref="Account"/> collection result.
+    /// Represents the <c>Account</c> collection result.
     /// </summary>
     public class AccountCollectionResult : CollectionResult<AccountCollection, Account>
     {

samples/Cdr.Banking/Cdr.Banking.Common/Entities/Generated/AccountArgs.cs

@@ -11,7 +11,7 @@
 namespace Cdr.Banking.Common.Entities
 {
     /// <summary>
-    /// Represents the <see cref="Account"/> arguments entity.
+    /// Represents the <c>Account</c> arguments entity.
     /// </summary>
     public partial class AccountArgs
     {

samples/Cdr.Banking/Cdr.Banking.Common/Entities/Generated/AccountDetail.cs

@@ -11,7 +11,7 @@
 namespace Cdr.Banking.Common.Entities
 {
     /// <summary>
-    /// Represents the <see cref="Account"/> Detail entity.
+    /// Represents the <c>Account</c> Detail entity.
     /// </summary>
     public partial class AccountDetail : Account
     {

samples/Cdr.Banking/Cdr.Banking.Common/Entities/Generated/AccountUType.cs

@@ -17,7 +17,7 @@ namespace Cdr.Banking.Common.Entities
     public partial class AccountUType : ReferenceDataBase<Guid> { }
 
     /// <summary>
-    /// Represents the <see cref="AccountUType"/> collection.
+    /// Represents the <c>AccountUType</c> collection.
     /// </summary>
     public partial class AccountUTypeCollection : List<AccountUType> { }
 }

samples/Cdr.Banking/Cdr.Banking.Common/Entities/Generated/Balance.cs

@@ -16,7 +16,7 @@ namespace Cdr.Banking.Common.Entities
     public partial class Balance : IIdentifier<string>
     {
         /// <summary>
-        /// Gets or sets the <see cref="Account"/> identifier.
+        /// Gets or sets the <c>Account</c> identifier.
         /// </summary>
         [JsonPropertyName("accountId")]
         public string? Id { get; set; }