{"id":15692720,"url":"https://github.com/fleny113/endpointmapper","last_synced_at":"2025-05-08T03:15:57.652Z","repository":{"id":168753708,"uuid":"571167342","full_name":"Fleny113/EndpointMapper","owner":"Fleny113","description":"Endpoint Mapper for ASP.NET Core 8","archived":false,"fork":false,"pushed_at":"2023-12-23T10:51:35.000Z","size":170,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-08T03:15:51.895Z","etag":null,"topics":["aspnet-core","aspnetcore","dotnet-core","dotnet8","dotnetcore","openapi","sourcegeneration","sourcegenerator","swagger"],"latest_commit_sha":null,"homepage":"https://www.nuget.org/packages/EndpointMapper","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fleny113.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-27T11:47:15.000Z","updated_at":"2025-02-06T04:11:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"2c9e4be7-ca75-48f5-ad43-0cd6b62e01a3","html_url":"https://github.com/Fleny113/EndpointMapper","commit_stats":null,"previous_names":["fleny113/endpointmapper"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fleny113%2FEndpointMapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fleny113%2FEndpointMapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fleny113%2FEndpointMapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fleny113%2FEndpointMapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fleny113","download_url":"https://codeload.github.com/Fleny113/EndpointMapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252990004,"owners_count":21836668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aspnet-core","aspnetcore","dotnet-core","dotnet8","dotnetcore","openapi","sourcegeneration","sourcegenerator","swagger"],"created_at":"2024-10-03T18:39:12.584Z","updated_at":"2025-05-08T03:15:57.622Z","avatar_url":"https://github.com/Fleny113.png","language":"C#","readme":"# EndpointMapper\n\nBuilt on top of Minimal APIs and easy to use\n\n\u003e [!NOTE]\n\u003e If you are updating your project to use EndpointMapper v2 prerelease 3+ [see the update guide](#updating-to-v2-prerelease-3)\n\n## Installation\n\nAdd the package to your ASP.NET Core project\n\n```sh\ndotnet add package EndpointMapper\n\n# To add support for OpenAPI (See below for more instructions)\ndotnet add package EndpointMapper.OpenApi\n```\n\n## Requirements\n\n- [.NET 8][getDotnet]\n- [ASP.NET Core 8][getDotnet]\n\n## Usage\n\nAdd this into the `Program.cs`\n```cs\napp.MapEndpointMapperEndpoints();\n```\n\nThen create a public class that implements `IEndpoint` and add a static method with attribute `HttpMap(HttpMapMethod.Get, \"\u003croute\u003e\")`\nwhere you can change `HttpMapMethod.Get` to any other options for different HTTP verbs and `\"\u003croute\u003e\"` to one, or more, routes to map the endpoint to\n\n\u003e [!TIP]\n\u003e see [Samples](#sample) for an example\n\n\u003e [!NOTE]\n\u003e To bind parameters/inject dependencies to the method function [see more below](#parameters-binding-and-function-return)\n\u003e\n\u003e If you want to use Swagger [see this section](#openapi-support-swagger)\n\n### Sample\n\nProgram.cs:\n```csharp\nusing EndpointMapper;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nvar app = builder.Build();\n\napp.MapEndpointMapperEndpoints();\n\napp.Run();\n```\n\nThen create a file, in this case it's in the root of the project but it could be in any folder\n\nExampleEndpoint.cs:\n```csharp\nusing EndpointMapper;\n\npublic class ExampleEndpoint : IEndpoint\n{\n    [HttpMap(HttpMapMethod.Get, \"/example\")]\n    public static Ok\u003cstring\u003e Handle()\n    {\n        return TypedResults.Ok(\"Hello world from EndpointMapper\");\n    }\n}\n```\n\u003e [!NOTE]\n\u003e To bind parameters/inject dependencies to the method function [see more below](#parameters-binding-and-function-return)\n\n---\n\n## Parameters Binding and function return\n\nSince EndpointMapper uses the native ASP.NET mapping system to map your endpoint and make them work, you can threat\nyour method like the inline delegate to the `app.MapGet(...)` method.\n\nSo you can do:\n- Http Body, Query, Route, Headers binding into the function arguments\n- Dependency Injection from the method parameters\n- Attributes like `[FromBody]` or `[FromQuery]` to explicitly map the required values into arguments\n- Return using the `Results` or `TypedResults` methods or directly a `string` or any other values that ASP.NET\nautomatically can translate into a valid HTTP response body\n\nAn example of this can be seen in the [example](#sample) where `TypedResults` is used to send an 200 Status code\nresponse back with a body attached that contains a string saying `Hello world from EndpointMapper`\n\n---\n\n## OpenAPI support (swagger)\n\nEndpointMapper only supports `Swashbuckle.AspNetCore`, and you will need to add the `EndpointMapper.OpenApi` package\n\n\u003e [!WARNING]\n\u003e For [authentication](#authentication-requirements) or [XML documentation](#xml-documentation) you may need to add \n\u003e some code to your `.AddSwaggerGen(...)` call\n\n### XML documentation\n\nYou will need to add:\n\n- To your `.csproj`\n  - `\u003cGenerateDocumentationFile\u003etrue\u003c/GenerateDocumentationFile\u003e` to generate the XML file to use\n  - Optionally, `\u003cNoWarn\u003e$(NoWarn);CS1591\u003c/NoWarn\u003e` to disable the warning [`Missing XML comment for publicly visible type or member 'Type_or_Member'`][CS1591]\n\n- To the `.AddSwaggerGen()` call\n```csharp\n// Get the XML file path from the Assembly\nvar xmlFilename = $\"{Assembly.GetExecutingAssembly().GetName().Name}.xml\";\n\n// Add the comments into the generation for the OpenApi scheme\nconfig.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), includeControllerXmlComments: true);\n```\n\n\u003e [!NOTE] \n\u003e You may need to add `using System.Reflection;` because we use the `Assembly` class available in the \n\u003e `System.Reflection` namespace\n\n\u003e [!NOTE]\n\u003e In the code you need to add the action passed as first argument to `.AddSwaggerGen()`, `config` is the name\n\u003e of the variable to which the `SwaggerGenOption` instance is bound, if you named it in another way you'll need to change\n\u003e the code accordingly, if you're not sure about what you're doing, there is an example of the complete call to `.AddSwaggerGen()` to the [end of\n\u003e the swagger section](#addswaggergen-example-call)\n\n### Authentication requirements\n\nIf you have authentication in your application you need to let swagger know how to authenticate against it, you will\nneed to add to the `.AddSwaggerGen()` call the registration of Security Definition and if you use the ASP.NET\n`[Authorize]` attribute you may also need to add some code to detect the attribute and add the requirement\n\nEndpointMapper.OpenApi provides you an operation filter to add those requirements automatically when it detects the\n`[Authorize]` attribute, if you manually check for authentication using a Filter or something else then this is not\nneeded, and you will need something else to add the requirements\n\nThe only code you will need to add to your `.AddSwaggerGen()` call is the following\n```csharp\n// Add the security definition with name Bearer and the following options\nconfig.AddSecurityDefinition(\"Bearer\", new OpenApiSecurityScheme\n{\n    Name = \"Bearer JWT\",\n    Type = SecuritySchemeType.Http,\n    In = ParameterLocation.Header,\n    Scheme = \"Bearer\"\n});\n\n// Add the operationFilter to add the authentication requirements where needed\nconfig.OperationFilter\u003cAuthenticationRequirementOperationFilter\u003e();\n```\n\n\u003e [!NOTE]\n\u003e In the code you'll need to add the action passed as first argument to `.AddSwaggerGen()`, `config` it's the name\n\u003e of the variable to witch the `SwaggerGenOption` instance is bound, if you named it in another way you need to change\n\u003e the code accordingly, if you're not sure about what you're doing there is an example of the complete call to `.AddSwaggerGen()` at the [end of\n\u003e the swagger section](#addswaggergen-example-call)\n\n### AddSwaggerGen example call\n\nThis is an example call to the `.AddSwaggerGen()` method witch has both XML comments integration and user authentication\n\nThis call is here to help you understand the code snippet(s) in the context of the whole call, you may not copy-paste all\nthe function as (especially the authentication stuff) it requires edits based on your application needs, if you want more\ncontext you can refer to the `EndpointMapper.TestApplication/Program.cs` file\n\n```csharp\n// builder is the variable assigned to the return value of \"WebApplication.CreateBuilder()\"\nbuilder.Services.AddSwaggerGen(config =\u003e\n{\n    // Add the security definition with name Bearer and the following options\n    config.AddSecurityDefinition(\"Bearer\", new OpenApiSecurityScheme\n    {\n        Name = \"Bearer JWT\",\n        Type = SecuritySchemeType.Http,\n        In = ParameterLocation.Header,\n        Scheme = \"Bearer\"\n    });\n    \n    // Add the operationFilter to add the authentication requirements where needed\n    config.OperationFilter\u003cAuthenticationRequirementOperationFilter\u003e();\n    \n    // Get the XML file path from the Assembly\n    var xmlFilename = $\"{Assembly.GetExecutingAssembly().GetName().Name}.xml\";\n\n    // Add the comments into the generation for the OpenApi scheme\n    config.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), includeControllerXmlComments: true);\n});\n```\n\n---\n\n## Using a route group\n\nIn previous versions EndpointMapped used to have an option to prefix all the routes. Now this options doesn't exist anymore, [see the upgrade guide](#updating-to-v2-prerelease-3).\n\nTo still have the ability to prefix all your routes by using an ASP.NET Route Group, EndpointMapped used to use it under the hood\nbut now you have to use it yourself.\n\nYou can create a Route group by using the `MapGroup` method on the `WebApplication` or another route group, then\nyou can use the `MapEndpointMapperEndpoints` method on the Route group builder instance. If you wanted to configure the group\nyou can now simply use the Route group builder instance you just got.\n\nThis now allows to map multiple times your endpoints if you want, for example you could map all your endpoints to both `/api` and `/` if you wanted.\n\n## Endpoint configurations\n\n### Method based configuration\n\nYou may want to configure more some of your endpoints, but there is a problem. Since we are using `Attributes`\nto map our endpoints and ASP.NET Core doesn't provide attribute to specify a filter attribute, for example, for a minimal API\nit seems that we can't do much about this.\n\nFor this reason EndpointMapper allows you to specify a `Configure` method by implementing the `IConfigureEndpoint`,\nthis method gives you access to the `RouteHandlerBuilder`, the route the endpoint is being mapped to and the HTTP Method,\nthis way you can use the builder like if you were chaining methods to the result of `MapGet`, `MapPost`, ecc..\n\n\u003e [!WARNING]\n\u003e If you registered your endpoint with the [method based approach](#method-based-registration)\n\u003e EndpointMapper won't call the `Configure` method, as it is called for endpoints mapped by the `HttpMap` attribute,\n\u003e and you will need to do your configuration in the `Register` method\n\n\u003e [!NOTE]\n\u003e Since the `Configure` method is implemented on the class and EndpointMapper doesn't enforce the 1 handler for class, this\n\u003e method will be called for each endpoint you map in the class you implement the `Configure` method. To differentiate a \n\u003e route from another the function has 2 another `string` arguments, one it's the route the endpoint is being mapped to\n\u003e and the other one is the method that is being used to map the endpoint.\n\u003e\n\u003e There is one only thing to remember when having multiple endpoints in the class is that this method will be called for\n\u003e each route in each `HttpMap` attribute you have in the class. So if you have 2 methods, each with 2 attributes and 2 routes\n\u003e each you the `Configure` method will be called a total of 8 times, since in total you are mapping 8 different routes.\n\n### Method based registration\n\nIf you don't like using attributes to map your endpoints you can implement the `IRegisterEndpoint` interface and the\n`Register` method. In this method you have access to the `IEndpointRouteBuilder` you use to call the `MapEndpointMapperEndpoints`\nmethod, using the builder you can use the extension methods that ASP.NET Core declares to map all your endpoints,\nan example is the `MapGet` or `MapPost` method.\n\n\u003e [!WARNING]\n\u003e Don't use `Register` method if you need to configure your endpoints and you want to use the Attribute based mapping,\n\u003e for that you can use the [`Configure` method](#method-based-configuration)\n\n\u003e [!NOTE]\n\u003e EndpointMapper checks for both the `HttpMap` attribute and the `Register` method to register your endpoints\n\n## Updating to v2 prerelease 3+\n\nIn the prerelease 3 the public API of EndpointMapper changed quite a bit, so here are all the changes that have\nbeen made and you have to do to update your project.\n\n\u003e [!NOTE]\n\u003e If you are updating from v1 there is one extra thing to do.\n\u003e\n\u003e The swagger support is now optional, so you need to install the `EndpointMapper.OpenApi` nuget package \n\u003e and add `using EndpointMapper.OpenApi;` for the `AuthenticationRequirementOperationFilter`\n\n- `HttpMap\u003cHttpVerb\u003e(\u003croutes\u003e)` has now been replaced with `HttpMap(HttpMapMethod.\u003cHttpVerb\u003e, \u003croutes\u003e)`,\nso a `HttpMapGet(\"/myRoute\")` now is `HttpMap(HttpMapMethod.Get, \"/myRoute\")`\n- All your methods that have an `HttpMap` attribute now needs to be `static`\n- The constructor based DI is no longer supported. You now need to use the DI from the method parameters\n- The `Configure` method now has only 1 overload, `Configure(RouteHandlerBuilder, string route, string method)`\n- the `IEndpointConfigurationAttribute` interface and the `Filter\u003cT\u003e` attribute have been deleted. You now need to use the [method based configuration](#method-based-configuration)\n- `AddEndpointMapper\u003cT\u003e(this IServiceCollection, Action\u003cEndpointMapperConfiguration\u003e)`,\n`AddEndpointMapper(this IServiceCollection, Action\u003cEndpointMapperConfiguration\u003e, params Type[])` and\n`AddEndpointMapper(this IServiceCollection, Action\u003cEndpointMapperConfiguration\u003e, params Assembly[])` have been removed.\n- `UseEndpointMapper(this WebApplication, bool)` has been renamed to `MapEndpointMapperEndpoints(this IEndpointRouteBuilder)`\n- You need [.NET 8 and ASP.NET Core 8][getDotnet]\n- The finding of your endpoints is now done at compile time via a source generator and not a runtime using reflection. Now EndpointMapper is NativeAOT friendly.\n- The `LogTimeTookToInitialize` option doesn't exist anymore\n- The `RoutePrefix` and `ConfigureGroupBuilder` options do not exist anymore. You can still configure EndpointMapper to use \na [route prefix using a ASP.NET Route Group](#using-a-route-group)\n\nTo see all the changes that have been made to the EndpointMapper since v1 code you can check the [Github commits][gitCommits]\n\n[getDotnet]: https://get.dot.net/8\n[CS1591]: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/cs1591\n[gitCommits]: https://github.com/Fleny113/EndpointMapper/compare/08b4d3640586da116cff589b02cad5fab98e6cbb...main\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffleny113%2Fendpointmapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffleny113%2Fendpointmapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffleny113%2Fendpointmapper/lists"}