Skip to content

Commit 5d92b0a

Browse files
futurum-devfuturum-dev
committed
Improve README.md
1 parent ee56a99 commit 5d92b0a

File tree

1 file changed

+44
-88
lines changed

1 file changed

+44
-88
lines changed

‎README.md‎

Lines changed: 44 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -81,17 +81,20 @@ if (app.Environment.IsDevelopment())
8181

8282
app.Run();
8383
```
84+
**See *[program.cs](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/Program.cs)* in sample project**
8485

8586
#### AddWebApiEndpointsFor... (per project containing WebApiEndpoints)
86-
This will be automatically created by the source generator. You need to call this to have that project's WebApiEndpoints added to the pipeline.
87+
This will be automatically created by the source generator.
88+
89+
You need to call this for each project that contains WebApiEndpoints, in order for them to be added to the pipeline.
8790

8891
e.g.
8992
```csharp
9093
builder.Services.AddWebApiEndpointsForFuturumWebApiEndpointMicroSample();
9194
```
9295

9396
#### UseWebApiEndpoints
94-
Adds the WebApiEndpoints to the pipeline
97+
Adds the WebApiEndpoints to the pipeline and does various other setup needed for the WebApiEndpoints to work.
9598
```csharp
9699
app.UseWebApiEndpoints();
97100
```
@@ -102,21 +105,21 @@ Register the OpenApi UI (Swagger and SwaggerUI) middleware. This is usually only
102105
app.UseWebApiEndpointsOpenApi();
103106
```
104107

105-
### WebApiEndpoint
106-
1. Create a new partial class
107-
2. Add the *WebApiEndpoint* attribute to the class, with the *route prefix* and optionally a *tag*
108-
3. Add the *WebApiEndpointVersion* attribute to the class, if you want to specify a specific *ApiVersion*
109-
4. Implement the *Build* method and add *minimal api(s)* as per usual
108+
### How to create a WebApiEndpoint
109+
1. Create a new partial class.
110+
2. Add the *WebApiEndpoint* attribute to the class, with the *route prefix* for all the REST methods in this WebApiEndpoint. You can also optionally add a *tag*. This is used in the OpenApi documentation. If you do not specify a tag, then the route prefix is used.
111+
3. Add the *WebApiEndpointVersion* attribute to the class, if you want to specify a specific *ApiVersion*. If you do not specify a specific *ApiVersion*, then the default *ApiVersion* is used. You can add multiple *WebApiEndpointVersion* attributes to the class, if you want to support multiple *ApiVersions*.
112+
4. Implement the *Build* method and add *minimal api(s)* as per usual.
110113
5. *Optionally* implement the *Configure* method to configuration the *WebApiEndpoint*
111114

112115
#### Build
113116
You can *map* your minimal apis for this WebApiEndpoint in the *Build* method.
114117

115-
The *IEndpointRouteBuilder* parameter is already:
116-
- configured with [configuring for the entire API](#configuring-the-entire-api)
117-
- configured with the API versioning
118-
- configured with [configuring a specific API version](#configuring-a-specific-api-version)
119-
- configured with the route prefix and tag
118+
The *IEndpointRouteBuilder* that the *Build* method receives has already:
119+
- been configured with [configuring for the entire API](#configuring-the-entire-api)
120+
- been configured with the API versioning
121+
- been configured with [configuring a specific API version](#configuring-a-specific-api-version)
122+
- been configured with the route prefix and tag
120123
- been through the *optional* *[Configure](#configure)* method in the same class
121124

122125
```csharp
@@ -126,7 +129,6 @@ protected override void Build(IEndpointRouteBuilder builder)
126129
```
127130

128131
##### Full example
129-
###### Weather
130132
```csharp
131133
[WebApiEndpoint("weather")]
132134
public partial class WeatherWebApiEndpoint
@@ -147,104 +149,55 @@ public partial class WeatherWebApiEndpoint
147149
.ToOk();
148150
}
149151
```
152+
**See *[WeatherWebApiEndpoint](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/WeatherForecast/WeatherWebApiEndpoint.cs)* in sample project**
150153

151-
###### File download
152-
```csharp
153-
[WebApiEndpoint("bytes", "feature")]
154-
public partial class BytesWebApiEndpoint
155-
{
156-
protected override void Build(IEndpointRouteBuilder builder)
157-
{
158-
builder.MapGet("download", DownloadHandler);
159-
}
160-
161-
private static Results<NotFound, FileContentHttpResult, BadRequest<ProblemDetails>> DownloadHandler(HttpContext context)
162-
{
163-
return Run(Execute, context, "Failed to read file");
164-
165-
Results<NotFound, FileContentHttpResult> Execute()
166-
{
167-
var path = "./Data/hello-world.txt";
168-
169-
if (!File.Exists(path))
170-
{
171-
return TypedResults.NotFound();
172-
}
173-
174-
var bytes = File.ReadAllBytes(path);
175-
return TypedResults.Bytes(bytes, MediaTypeNames.Application.Octet, "hello-world.txt");
176-
}
177-
}
178-
}
179-
```
180-
181-
### Configure
182-
You can *optionally* configure the WebApiEndpoint in the *Configure* method
154+
#### Configure
155+
You can *optionally* configure the WebApiEndpoint in the *Configure* method.
183156

184157
```csharp
185158
protected override RouteGroupBuilder Configure(RouteGroupBuilder groupBuilder, WebApiEndpointVersion webApiEndpointVersion)
186159
{
187160
}
188161
```
189162

190-
##### Full example
191-
###### RateLimiting
192-
```csharp
193-
[WebApiEndpoint("rate-limiting")]
194-
public partial class RateLimitingWebApiEndpoint
195-
{
196-
protected override RouteGroupBuilder Configure(RouteGroupBuilder groupBuilder, WebApiEndpointVersion webApiEndpointVersion)
197-
{
198-
return groupBuilder.RequireRateLimiting(RateLimiting.SlidingWindow.Policy);
199-
}
200-
201-
protected override void Build(IEndpointRouteBuilder builder)
202-
{
203-
builder.MapGet("/", GetHandler);
204-
}
205-
206-
private static Ok<DataCollectionDto<FeatureDto>> GetHandler(HttpContext context) =>
207-
Enumerable.Range(0, 10)
208-
.Select(i => new Feature($"Name - {i}"))
209-
.Select(FeatureMapper.Map)
210-
.ToDataCollectionDto()
211-
.ToOk();
212-
}
213-
```
214-
215-
This allows you to set properties on the RouteGroupBuilder. This will effect all minimal apis in the *Build* method.
163+
This allows you to setup the RouteGroupBuilder. This will effect all minimal apis in this classes *Build* method.
216164

217165
You can also configure it differently per ApiVersion.
218166

219-
#### This ia a good place to add a *EndpointFilter*
167+
#### This ia a good place to add a WebApiEndpoint specific *EndpointFilter*
220168
```csharp
221169
groupBuilder.AddEndpointFilter<CustomEndpointFilter>();
222170
```
223-
#### This ia a good place to add a *RateLimiting*
171+
**See *[EndpointFilterWebApiEndpoint](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/Features/EndpointFilterWebApiEndpoint.cs)* in sample project**
172+
173+
#### This ia a good place to add a WebApiEndpoint specific *RateLimiting*
224174
```csharp
225175
groupBuilder.RequireRateLimiting(RateLimiting.SlidingWindow.Policy);
226176
```
227-
#### This ia a good place to add a *OutputCache*
228-
177+
**See *[RateLimitingWebApiEndpoint](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/Features/RateLimitingWebApiEndpoint.cs)* in sample project**
178+
179+
#### This ia a good place to add a WebApiEndpoint specific *OutputCache*
229180
```csharp
230181
groupBuilder.CacheOutput(OutputCaching.ExpiryIn10Seconds.Policy);
231182
```
183+
**See *[OutputCachingWebApiEndpoint](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/Features/OutputCachingWebApiEndpoint.cs)* in sample project**
232184

233-
#### This ia a good place to add *Security*
185+
#### This ia a good place to add WebApiEndpoint specific *Security*
234186
```csharp
235187
groupBuilder.RequireAuthorization(Authorization.Permission.Admin);
236188
```
189+
**See *[SecurityProtectedWebApiEndpoint](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/Security/SecurityProtectedWebApiEndpoint.cs)* in sample project**
237190

238-
## Configure
191+
## Configuration
239192
### Configuring Futurum.WebApiEndpoint.Micro
240-
Allows you to configure:
193+
This allows you to configure:
241194
- DefaultApiVersion *(mandatory)*
242-
- This is used if a specific ApiVersion is not provided for a specific WebApiEndpoint
195+
- This is used if a ApiVersion is not provided for a specific WebApiEndpoint.
243196
- OpenApi
244197
- DefaultInfo *(optional)*
245-
- This is used if a specific OpenApiInfo is not provided for a specific ApiVersion
198+
- This is used if a OpenApiInfo is not provided for a specific ApiVersion
246199
- VersionedInfo *(optional)*
247-
- Allowing you to have different OpenApiInfo per ApiVersion
200+
- Allowing you to have an OpenApiInfo per a specific ApiVersion. If you do not provide an OpenApiInfo for a specific ApiVersion, then the DefaultInfo is used.
248201
- Version
249202
- Prefix *(optional)*
250203
- Format *(optional)*
@@ -274,6 +227,7 @@ builder.Services
274227
}
275228
});
276229
```
230+
**See *[program.cs](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/Program.cs)* in sample project**
277231

278232
### Configuring the entire API
279233
The entire API can be configured. This is a good place to configure things like:
@@ -282,7 +236,7 @@ The entire API can be configured. This is a good place to configure things like:
282236

283237
The class must implement *IGlobalWebApiEndpoint* interface
284238

285-
** NOTE - there can only be one of these classes. **
239+
** NOTE - there can only be one of these classes. There is an [analyser](#roslyn-analysers) to check for this. **
286240

287241
** NOTE - this is applied before the version route is created. **
288242

@@ -296,16 +250,17 @@ public class GlobalWebApiEndpoint : IGlobalWebApiEndpoint
296250
}
297251
}
298252
```
253+
**See *[GlobalWebApiEndpoint](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/GlobalWebApiEndpoint.cs)* in sample project**
299254

300255
### Configuring a specific API version
301256
A specific API version can be configured. This is a good place to configure things like:
302257
- API version specific authorization (don't forget to set *AllowAnonymous* on the individual WebApiEndpoint that you don't want to be secured i.e. *Login* endpoint)
303258

304259
The class must:
305260
- implement *IWebApiVersionEndpoint* interface
306-
- be decorated with at least one *WebApiVersionEndpointVersion* attribute
261+
- be decorated with at least one *WebApiVersionEndpointVersion* attribute, for the version(s) it applies to
307262

308-
** NOTE - there can only be one of these classes per version. **
263+
** NOTE - there can only be one of these classes per version. There is an [analyser](#roslyn-analysers) to check for this. **
309264

310265
** NOTE - this is applied after the version route is created, but before the WebApiEndpoint specific route is created. **
311266

@@ -320,6 +275,7 @@ public class WebApiVersionEndpoint3_0 : IWebApiVersionEndpoint
320275
}
321276
}
322277
```
278+
**See *[WebApiVersionEndpoint3_0a](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/blob/main/sample/Futurum.WebApiEndpoint.Micro.Sample/WebApiVersionEndpoint3_0.cs)* in sample project**
323279

324280
## Sandbox runner
325281
### Run and RunAsync - If your code returns an *IResult*
@@ -625,8 +581,8 @@ ExceptionToProblemDetailsMapperService.Add<CustomException>((exception, httpCont
625581
{
626582
Detail = "An custom error occurred.",
627583
Instance = httpContext.Request.Path,
628-
Status = (int)HttpStatusCode.InternalServerError,
629-
Title = ReasonPhrases.GetReasonPhrase((int)HttpStatusCode.InternalServerError)
584+
Status = StatusCodes.Status500InternalServerError,
585+
Title = ReasonPhrases.GetReasonPhrase(StatusCodes.Status500InternalServerError)
630586
});
631587
```
632588

@@ -638,8 +594,8 @@ ExceptionToProblemDetailsMapperService.OverrideDefault((exception, httpContext,
638594
{
639595
Detail = "An error occurred.",
640596
Instance = httpContext.Request.Path,
641-
Status = (int)HttpStatusCode.InternalServerError,
642-
Title = ReasonPhrases.GetReasonPhrase((int)HttpStatusCode.InternalServerError)
597+
Status = StatusCodes.Status500InternalServerError,
598+
Title = ReasonPhrases.GetReasonPhrase(StatusCodes.Status500InternalServerError)
643599
});
644600
```
645601

0 commit comments

Comments
 (0)