Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nikiforovall/result-endpoints-template
Explore the use of TypedResults in .NET endpoints to achieve a consistent and strongly typed APIs
https://github.com/nikiforovall/result-endpoints-template
aspnetcore dotnet openapi template webapi
Last synced: about 1 month ago
JSON representation
Explore the use of TypedResults in .NET endpoints to achieve a consistent and strongly typed APIs
- Host: GitHub
- URL: https://github.com/nikiforovall/result-endpoints-template
- Owner: NikiforovAll
- License: mit
- Created: 2024-08-16T11:17:23.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-08-17T19:51:32.000Z (3 months ago)
- Last Synced: 2024-10-14T05:01:28.504Z (about 1 month ago)
- Topics: aspnetcore, dotnet, openapi, template, webapi
- Language: CSS
- Homepage: https://nikiforovall.github.io/dotnet/2024/08/17/result-endpoints.html
- Size: 29.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Nall.ResultEndpoints.Template
[](https://github.com/NikiforovAll/result-endpoints-template/actions/workflows/build.yml)
[](https://github.com/NikiforovAll/result-endpoints-template/actions/workflows/codeql-analysis.yml)
[](https://nuget.org/packages/Nall.ResultEndpoints.Template)
[](https://conventionalcommits.org)
[](https://github.com/nikiforovall/result-endpoints-template/blob/main/LICENSE.md)
This is a template for creating a new minimal API project with [Ardalis.ApiEndpoints](https://github.com/ardalis/ApiEndpoints) that utilizes the TypedResults in Endpoint (aka replacement for MVC Controllers for Web APIs).
```csharp
public class HelloWorld : EndpointBaseSync.WithRequest.WithResult>
{
[EndpointSummary("Says hello")]
[EndpointDescription("Says hello based on the request")]
[Tags("Hello")]
[EndpointName(nameof(HelloWorld))]
[HttpGet("/hello-world")]
public override Ok Handle([FromQuery(Name = "q")] string request)
{
if (request == "error")
{
throw new Exception("Something went wrong...");
}
return TypedResults.Ok($"Hello, {request}");
}
}
```
## Installation
```bash
dotnet new install Nall.ResultEndpoints.Template
```
Verify installation:
```bash
dotnet new list result-endpoints-api
# These templates matched your input: 'result-endpoints-api'
# Template Name Short Name Language Tags
# ---------------- --------------------- -------- ----------------------------
# Result Endpoints -resultendpoints-api [C#] Web/API/Ardalis.ApiEndpoints
```
## Usage
```bash
dotnet new result-endpoints-api --dry-run
# File actions would have been taken:
# Create: ./.vscode/settings.json
# Create: ./Data/DbContext.cs
# Create: ./Endpoints/HelloWorld.cs
# Create: ./Endpoints/Todo/CreateTodo.cs
# Create: ./Endpoints/Todo/DeleteTodo.cs
# Create: ./Endpoints/Todo/GetTodo.cs
# Create: ./Endpoints/Todo/ListTodos.cs
# Create: ./Endpoints/Todo/UpdateTodo.cs
# Create: ./HttpResultsOperationFilter.cs
# Create: ./Program.cs
# Create: ./Properties/launchSettings.json
# Create: ./Seeder.cs
# Create: ./appsettings.Development.json
# Create: ./appsettings.json
# Create: ./content.csproj
```
## Main takeaways
* `TypedResults` directly contributes to OpenAPI. And the ancillary `Results` class describes discriminated unions for the response types.
* `TypedResults` can be used in MVC Controllers and Minimal APIs.
* `Ardalis.ApiEndpoints` is built on top of Controllers, therefore we can use it in conjunction with `TypedResults`.
* `Ardales.ApiEndpoints` has two main classes: `EndpointBaseSync` and `EndpointBaseAsync`, both inherits from `ControllerBase`. It means that automatic model validation is enabled by default. This is why we need to extend generated OpenAPI definition with additional responses produced by model validation. I.e.: in API scenarios, we can add `ProblemDetails` as the way to report validation errors.
* Another important aspect, is exception handling, although, it is not recommended to throw exceptions from client code, sometimes it is inevitable. In this case, exceptions are handled by global error handler. Exceptions are transformed into `ProblemDetails` and returned to the client.
* We can use `EndpointSummary`, `EndpointDescription`, `EndpointName` to extend generated OpenAPI definition in library agnostic way.
## References
-
-
-
-
-