Merge pull request #22 from marcominerva/develop

Add OpenApi project
marcominerva · Jan 23, 2023 · 1b71a02 · 1b71a02
2 parents 90fc20e + c7986e7
commit 1b71a02
Show file tree

Hide file tree

Showing 17 changed files with 351 additions and 78 deletions.
diff --git a/.github/workflows/publish_openapi.yml b/.github/workflows/publish_openapi.yml
@@ -0,0 +1,53 @@
+name: Publish OpenApi Helpers on NuGet
+
+on:
+  push:
+    branches: [ master ]
+    paths: [ 'src/MinimalHelpers.OpenApi/**' ]
+  workflow_dispatch:
+
+env:
+  NET_VERSION: '7.x'
+  PROJECT_NAME: src/MinimalHelpers.OpenApi 
+  PROJECT_FILE: MinimalHelpers.OpenApi.csproj
+  TAG_NAME: openapi
+  RELEASE_NAME: MinimalHelpers.OpenApi
+
+jobs:
+  publish:
+    name: Publish on NuGet
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0 # avoid shallow clone so nbgv can do its work.
+
+    - name: Setup .NET SDK ${{ env.NET_VERSION }}
+      uses: actions/setup-dotnet@v3
+      with:
+        dotnet-version: ${{ env.NET_VERSION }}
+        dotnet-quality: 'ga'
+
+    - name: Nerdbank.GitVersioning 
+      uses: dotnet/[email protected]
+      id: nbgv
+      with:        
+        path: ${{ env.PROJECT_NAME }}
+
+    - name: Package
+      run: dotnet pack -c Release -o . '${{ env.PROJECT_NAME }}/${{ env.PROJECT_FILE }}'
+
+    - name: Publish on NuGet
+      run: dotnet nuget push *.nupkg -k ${{ secrets.NUGET_API_KEY }} -s https://api.nuget.org/v3/index.json  
+
+    - name: Create release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+      with:
+          tag_name: ${{ env.TAG_NAME }}_v${{ steps.nbgv.outputs.NuGetPackageVersion }}
+          release_name: ${{ env.RELEASE_NAME }} ${{ steps.nbgv.outputs.NuGetPackageVersion }}
+          draft: false
+          prerelease: false
diff --git a/.github/workflows/publish.yml → .github/workflows/publish_routing.yml b/.github/workflows/publish.yml → .github/workflows/publish_routing.yml
@@ -1,15 +1,17 @@
-name: Publish on NuGet
+name: Publish Routing Helpers on NuGet
 
 on:
   push:
     branches: [ master ]
-    paths: [ 'src/**' ]
+    paths: [ 'src/MinimalHelpers.Routing/**' ]
   workflow_dispatch:
 
 env:
   NET_VERSION: '7.x'
   PROJECT_NAME: src/MinimalHelpers.Routing 
-  PROJECT_FILE: MinimalHelpers.Routing.csproj  
+  PROJECT_FILE: MinimalHelpers.Routing.csproj
+  TAG_NAME: routing
+  RELEASE_NAME: MinimalHelpers.Routing
 
 jobs:
   publish:
@@ -45,7 +47,7 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
       with:
-          tag_name: v${{ steps.nbgv.outputs.NuGetPackageVersion }}
-          release_name: Release ${{ steps.nbgv.outputs.NuGetPackageVersion }}
+          tag_name: ${{ env.TAG_NAME }}_v${{ steps.nbgv.outputs.NuGetPackageVersion }}
+          release_name: ${{ env.RELEASE_NAME }} ${{ steps.nbgv.outputs.NuGetPackageVersion }}
           draft: false
           prerelease: false
diff --git a/.gitignore b/.gitignore
@@ -348,3 +348,6 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+/src/MinimalHelpers.Routing/MinimalHelpers.Routing.xml
+/src/MinimalHelpers.OpenApi/MinimalHelpers.OpenApi.xml
diff --git a/MinimalHelpers.Routing.sln → MinimalHelpers.sln b/MinimalHelpers.Routing.sln → MinimalHelpers.sln
@@ -17,6 +17,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MinimalSample.Handlers", "s
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{72739819-7239-4B73-86BF-1E944D123C88}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MinimalHelpers.OpenApi", "src\MinimalHelpers.OpenApi\MinimalHelpers.OpenApi.csproj", "{A4DDF9B4-7D23-4FF9-9259-89C7179A7DC8}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -35,6 +37,10 @@ Global
 		{871982DC-EBA8-4BAE-A436-42C5E00E3BA1}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{871982DC-EBA8-4BAE-A436-42C5E00E3BA1}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{871982DC-EBA8-4BAE-A436-42C5E00E3BA1}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A4DDF9B4-7D23-4FF9-9259-89C7179A7DC8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A4DDF9B4-7D23-4FF9-9259-89C7179A7DC8}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A4DDF9B4-7D23-4FF9-9259-89C7179A7DC8}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A4DDF9B4-7D23-4FF9-9259-89C7179A7DC8}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

diff --git a/README.md b/README.md
@@ -1,17 +1,22 @@
-# Minimal APIs Routing Helpers
+# Minimal APIs Helpers
 
 [![Lint Code Base](https://github.com/marcominerva/MinimalHelpers.Routing/actions/workflows/linter.yml/badge.svg)](https://github.com/marcominerva/MinimalHelpers.Routing/actions/workflows/linter.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/marcominerva/MinimalHelpers.Routing/blob/master/LICENSE)
+
+A collection of helpers libraries for Minimal API projects.
+
+## MinimalHelpers.Routing
+
 [![Nuget](https://img.shields.io/nuget/v/MinimalHelpers.Routing)](https://www.nuget.org/packages/MinimalHelpers.Routing)
 [![Nuget](https://img.shields.io/nuget/dt/MinimalHelpers.Routing)](https://www.nuget.org/packages/MinimalHelpers.Routing)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/marcominerva/MinimalHelpers.Routing/blob/master/LICENSE)
 
 A library that provides Routing helpers for Minimal API projects, mainly for automatic endpoints registration.
 
 **Installation**
 
-The library is available on [NuGet](https://www.nuget.org/packages/MinimalHelpers.Routing). Just search *MinimalHelpers.Routing* in the **Package Manager GUI** or run the following command in the **Package Manager Console**:
+The library is available on [NuGet](https://www.nuget.org/packages/MinimalHelpers.Routing). Just search for *MinimalHelpers.Routing* in the **Package Manager GUI** or run the following command in the **.NET CLI**:
 
-    Install-Package MinimalHelpers.Routing
+    dotnet add package MinimalHelpers.Routing
 
 **Usage**
 
@@ -57,6 +62,106 @@ You can also explicitly decide what types (among the ones that implement the `IR
         return true;
     });
 
+## MinimalHelpers.OpenApi
+
+[![Nuget](https://img.shields.io/nuget/v/MinimalHelpers.OpenApi)](https://www.nuget.org/packages/MinimalHelpers.OpenApi)
+[![Nuget](https://img.shields.io/nuget/dt/MinimalHelpers.OpenApi)](https://www.nuget.org/packages/MinimalHelpers.OpenApi)
+
+A library that provides OpenApi helpers for Minimal API projects.
+
+**Installation**
+
+The library is available on [NuGet](https://www.nuget.org/packages/MinimalHelpers.OpenApi). Just search for *MinimalHelpers.OpenApi* in the **Package Manager GUI** or run the following command in the **.NET CLI**:
+
+    dotnet add package MinimalHelpers.OpenApi
+
+**Usage**
+
+***Add missing schema in Swagger documentation***
+
+Unlike Controllers, current version of Minimal API does not generate the correct schema in Swagger documentation for certain file types, like `Guid`, `DateTime`, `DateOnly` and `TimeOnly`. For example, given the following endpoint:
+
+    app.MapGet("/api/schemas",
+        (Guid id, DateTime dateTime, DateOnly date, TimeOnly time) => TypedResults.NoContent());
+
+**swagger.json** will not contain **format** specification for these data types (whereas Controllers correctly set them):
+
+    "parameters": [
+      {
+        "name": "id",
+        // ...
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "dateTime",
+        // ...
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "date",
+        // ...
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "time",
+        // ...
+        "schema": {
+          "type": "string"
+        }
+      }
+    ]
+
+To solve the issue, just call the following extension method:
+
+    builder.Services.AddSwaggerGen(options =>
+    {
+        // using MinimalHelpers.OpenApi;
+        options.AddMissingSchemas();
+    });
+
+And you'll see that the correct **format** attribute has been specified for each parameter.
+
+    "parameters": [
+      {
+        "name": "id",
+        // ...
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      {
+        "name": "dateTime",
+        // ...
+        "schema": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      {
+        "name": "date",
+        // ...
+        "schema": {
+          "type": "string",
+          "format": "date"
+        }
+      },
+      {
+        "name": "time",
+        // ...
+        "schema": {
+          "type": "string",
+          "format": "time"
+        }
+      }
+    ]
+
 **Contribute**
 
 The project is constantly evolving. Contributions are welcome. Feel free to file issues and pull requests on the repo and we'll address them as we can. 
diff --git a/samples/MinimalSample.Handlers/MinimalSample.Handlers.csproj b/samples/MinimalSample.Handlers/MinimalSample.Handlers.csproj
@@ -6,6 +6,10 @@
 		<Nullable>enable</Nullable>
 	</PropertyGroup>
 
+    <ItemGroup>
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.2" />
+    </ItemGroup>
+
 	<ItemGroup>
 		<ProjectReference Include="..\..\src\MinimalHelpers.Routing\MinimalHelpers.Routing.csproj" />
 	</ItemGroup>

diff --git a/samples/MinimalSample.Handlers/SuppliersHandler.cs b/samples/MinimalSample.Handlers/SuppliersHandler.cs
@@ -11,20 +11,20 @@ public void MapEndpoints(IEndpointRouteBuilder endpoints)
     {
         endpoints.MapGet("/api/suppliers", GetList);
         endpoints.MapGet("/api/suppliers/{id:guid}", Get);
-        endpoints.MapPost("/api/suppliers", Insert);
+        endpoints.MapPost("/api/suppliers", Insert).WithOpenApi();
         endpoints.MapPut("/api/suppliers/{id:guid}", Update);
         endpoints.MapDelete("/api/suppliers/{id:guid}", Delete);
     }
 
-    private static IResult GetList() => Results.NoContent();
+    private static IResult GetList() => TypedResults.NoContent();
 
-    private static IResult Get(Guid id) => Results.NoContent();
+    private static IResult Get(Guid id) => TypedResults.NoContent();
 
-    private static IResult Insert(Supplier Person) => Results.NoContent();
+    private static IResult Insert(Supplier Person, DateTime? creationDate) => TypedResults.NoContent();
 
-    private static IResult Update(Supplier Person) => Results.NoContent();
+    private static IResult Update(Supplier Person) => TypedResults.NoContent();
 
-    private static IResult Delete(Guid id) => Results.NoContent();
+    private static IResult Delete(Guid id) => TypedResults.NoContent();
 }
 
 public record class Supplier(string Name);
diff --git a/samples/MinimalSample/Handlers/PeopleHandler.cs b/samples/MinimalSample/Handlers/PeopleHandler.cs
@@ -13,15 +13,15 @@ public void MapEndpoints(IEndpointRouteBuilder endpoints)
         endpoints.MapDelete("/api/people/{id:guid}", Delete);
     }
 
-    private static IResult GetList() => Results.NoContent();
+    private static IResult GetList() => TypedResults.NoContent();
 
-    private static IResult Get(Guid id) => Results.NoContent();
+    private static IResult Get(Guid id) => TypedResults.NoContent();
 
-    private static IResult Insert(Person Person) => Results.NoContent();
+    private static IResult Insert(Person Person) => TypedResults.NoContent();
 
-    private static IResult Update(Person Person) => Results.NoContent();
+    private static IResult Update(Person Person) => TypedResults.NoContent();
 
-    private static IResult Delete(Guid id) => Results.NoContent();
+    private static IResult Delete(Guid id) => TypedResults.NoContent();
 }
 
 public record class Person(string FirstName, string LastName);
diff --git a/samples/MinimalSample/Handlers/ProductsHandler.cs b/samples/MinimalSample/Handlers/ProductsHandler.cs
@@ -13,15 +13,15 @@ public void MapEndpoints(IEndpointRouteBuilder endpoints)
         endpoints.MapDelete("/api/products/{id:guid}", Delete);
     }
 
-    private static IResult GetList() => Results.NoContent();
+    private static IResult GetList() => TypedResults.NoContent();
 
-    private static IResult Get(Guid id) => Results.NoContent();
+    private static IResult Get(Guid id) => TypedResults.NoContent();
 
-    private static IResult Insert(Product Person) => Results.NoContent();
+    private static IResult Insert(Product Person) => TypedResults.NoContent();
 
-    private static IResult Update(Product Person) => Results.NoContent();
+    private static IResult Update(Product Person) => TypedResults.NoContent();
 
-    private static IResult Delete(Guid id) => Results.NoContent();
+    private static IResult Delete(Guid id) => TypedResults.NoContent();
 }
 
 public record class Product(string Name, string Description, double UnitPrice);
diff --git a/samples/MinimalSample/MinimalSample.csproj b/samples/MinimalSample/MinimalSample.csproj
@@ -7,10 +7,12 @@
 	</PropertyGroup>
 
 	<ItemGroup>
-		<PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
+		<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.2" />
+		<PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
 	</ItemGroup>
 
 	<ItemGroup>
+		<ProjectReference Include="..\..\src\MinimalHelpers.OpenApi\MinimalHelpers.OpenApi.csproj" />
 		<ProjectReference Include="..\..\src\MinimalHelpers.Routing\MinimalHelpers.Routing.csproj" />
 		<ProjectReference Include="..\MinimalSample.Handlers\MinimalSample.Handlers.csproj" />
 	</ItemGroup>

diff --git a/samples/MinimalSample/Program.cs b/samples/MinimalSample/Program.cs
@@ -1,10 +1,15 @@
+using MinimalHelpers.OpenApi;
 using MinimalHelpers.Routing;
 using MinimalSample.Handlers;
 
 var builder = WebApplication.CreateBuilder(args);
 
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen();
+
+builder.Services.AddSwaggerGen(options =>
+{
+    options.AddMissingSchemas();
+});
 
 var app = builder.Build();
 
@@ -34,4 +39,6 @@
 //    return true;
 //});
 
+app.MapGet("/api/schemas", (Guid id, DateTime dateTime, DateOnly date, TimeOnly time) => TypedResults.NoContent());
+
 app.Run();