Skip to content

Commit

Permalink
Added documentation for 4.x updates and an example for setting up a n…
Browse files Browse the repository at this point in the history
…ew web-api project with ApiEndpoints (#209)
  • Loading branch information
Asafima authored Jun 25, 2024
1 parent 9a5ccf4 commit 90fb33f
Showing 1 changed file with 146 additions and 8 deletions.
154 changes: 146 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ A HUGE Thank-You to [AWS](https://github.com/aws) for sponsoring this project in

If you like or are using this project to learn or start your solution, please give it a star. Thanks!

## Discover a Practical Example

If you're eager to dive into a practical example of using `Ardalis.ApiEndpoints`, check out our [Getting Started guide](#3-getting-started). This guide walks you through setting up your environment and creating your first API endpoint using the latest features in version 4.x.

## Upgrade to 4.x Notes

The fluent generics and base types involved in ApiEndpoints were updated in version 4.x, resulting in breaking changes. The updates required should be pretty straightforward, and have a few additional features that weren't supported in previous versions.
Expand Down Expand Up @@ -56,6 +60,14 @@ For version 3.0 we implemented a new way to define the base classes using "fluen

[3. Getting Started](#3-getting-started)

- [Set Up an Empty Web API Project](#set-up-an-empty-web-api-project)

- [Adding Controllers with Ardalis.ApiEndpoints](#adding-controllers-with-ardalisapiendpoints)

- [Adding common endpoint groupings using Swagger](#adding-common-endpoint-groupings-using-swagger)

- [File Upload Example](#file-upload-example)

[4. Animated Screenshots](#4-animated-screenshots)

[5. Open Questions](#5-open-questions)
Expand Down Expand Up @@ -98,15 +110,141 @@ Most REST APIs have groups of endpoints for a given resource. In Controller-base

## 3. Getting Started

I'll look to add detailed documentation in the future but for now here's all you need to get started (you can also check the sample project):
### Set Up an Empty Web API Project

#### Overview

When starting a new Web API project using .NET, you might want to begin with an empty project structure to have more control over dependencies and configurations.

#### Setting Up the Project

1. **Create the Project:**

Start by creating a new empty web API project. You can do this using the .NET CLI:

```bash
dotnet new web -n MyWebApi
cd MyWebApi
```

This creates a basic project structure for a web application.

2. **Update Program.cs:**

Open the `Program.cs` file, which serves as the entry point for your application. By default, it might contain the following code:

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// app.MapGet("/", () => "Hello World!");
app.Run();
```

Remove the `app.MapGet("/", () => "Hello World!");` line as it sets up a minimal endpoint which we'll replace with controller routing.

3. **Configure Services and Routing:**

Modify the `Program.cs` file to include controller services and routing:

```csharp
var builder = WebApplication.CreateBuilder(args);

// Add controllers
builder.Services.AddControllers();

var app = builder.Build();

// Map controllers to endpoints
app.MapControllers();

app.Run();
```

- **`builder.Services.AddControllers()`**: Adds services required for controllers to handle HTTP requests.
- **`app.MapControllers()`**: Maps controllers to appropriate endpoints based on routing attributes and conventions.

These two methods are required for the endpoint to work.

### Adding Controllers with Ardalis.ApiEndpoints

1. **Install Ardalis.ApiEndpoints NuGet Package**

Add the `Ardalis.ApiEndpoints` package to your ASP.NET Core web project. You can do this using the NuGet Package Manager or via the .NET CLI:

```bash
dotnet add package Ardalis.ApiEndpoints
```

2. **Create Endpoint Classes**

Create your endpoint classes by inheriting from `EndpointBaseSync` or `EndpointBaseAsync`, and add `.WithRequest<TRequest>` or `.WithResult<TResponse>`, or both, depending on whether your endpoint accepts input (POST) or simply returns a response (GET).

3. **Implement Handle Method**

Implement the `Handle` method from the base class (`EndpointBaseSync`) in your endpoint class. This method contains the logic to process the request and return the response.

```csharp
public class MyEndpoint : EndpointBaseSync
.WithRequest<string>
.WithActionResult<IActionResult>
{
[HttpGet("my-endpoint")]
public override ActionResult<IActionResult> Handle(string request)
{
// Your logic here
return Ok();
}
}
```

4. **Add Routing Attributes**

Decorate your `Handle` method with `[HttpGet]`, `[HttpPost]`, or other appropriate HTTP method attributes, specifying the route for your endpoint.

5. **Define Request and Response Types**

Define your `TRequest` and `TResponse` types in the same file as your endpoint class or in separate files as per your project structure.

6. **Test Your API Endpoint**

Test your ASP.NET Core API endpoint. If you're using Swagger/OpenAPI, it should automatically document your endpoint based on the attributes provided.

#### Example Endpoint Class

Here's an example of a GET endpoint that returns a list of books using `Ardalis.ApiEndpoints`:

```csharp
public class ListBooksEndpoint : EndpointBaseSync
.WithoutRequest
.WithResult<IList<BookDto>>
{
private readonly IRepository<Book> repository;
private readonly IMapper mapper;

public ListBooksEndpoint(
IRepository<Book> repository,
IMapper mapper)
{
this.repository = repository;
this.mapper = mapper;
}

[HttpGet("/books")]
public override IList<BookDto> Handle()
{
var books = repository.ListAll();

var bookDtos = books.Select(book => mapper.Map<BookDto>(book)).ToList();

return bookDtos;
}
}
```

1. Add the [Ardalis.ApiEndpoints NuGet package](https://www.nuget.org/packages/Ardalis.ApiEndpoints/) to your ASP.NET Core web project.
2. Create Endpoint classes by inheriting from either `EndpointBaseSync<TRequest,TResponse>` (for endpoints that accept a model as input) or `EndpointBaseSync<TResponse>` (for endpoints that simply return a response). For example, a POST endpoint that creates a resource and then returns the newly created record would use the version that includes both a Request and a Response. A GET endpoint that just returns a list of records and doesn't accept any arguments would use the second version.
3. Implement the base class's abstract `Handle()` method.
4. Make sure to add a `[HttpGet]` or similar attribute to your `Handle()` method, specifying its route.
5. Define your `TResponse` type in a file in the same folder as its corresponding endpoint (or in the same file if you prefer).
6. Define your `TRequest` type (if any) just like the `TResponse` class.
7. Test your ASP.NET Core API Endpoint. If you're using Swagger/OpenAPI it should just work with it automatically.
This endpoint demonstrates listing books and uses the `HttpGet` annotation.

### Adding common endpoint groupings using Swagger

Expand Down

0 comments on commit 90fb33f

Please sign in to comment.