Add an endpoint
This guide adds GET /api/movies/{id}/reviews, one page of the reviews written about a movie. The Application layer already has a GetReviewsQuery that filters by movie, so all the work happens in Presentation. That’s the point of the layers: new ways in, same rules underneath.
-
Add the aliases for the review types at the top of
src/Presentation/Endpoints/MovieEndpoints.cs. The file already aliases the movie types the same way.using Entities = Application.Movies.Entities;using Queries = Application.Movies.Queries;using ReviewEntities = Application.Reviews.Entities;using ReviewQueries = Application.Reviews.Queries; -
Map the route in
MapMovieEndpoints, after the existing two. The group already has the/api/moviesprefix and the Movies tag, so the new route inherits both, along with the authorization requirement if you created the solution with--include-auth._ = root.MapGet("/{id:guid}/reviews", GetMovieReviews).WithName(nameof(GetMovieReviews)).Produces<Page<ReviewEntities.Review>>().ProducesValidationProblem().ProducesProblem(StatusCodes.Status500InternalServerError); -
Add the handler to the same class. The XML comments aren’t decoration: they become the summary, description, parameter docs and response descriptions in the OpenAPI document, and Scalar shows every one of them.
/// <summary>/// List the Reviews of a Movie/// </summary>/// <remarks>/// Returns one page of the reviews written about a movie, along with the author of each.////// Sample request:////// GET /api/movies/3fa85f64-5717-4562-b3fc-2c963f66afa6/reviews?offset=0&limit=10/// </remarks>/// <param name="id">The unique identifier of the movie.</param>/// <param name="offset">The number of reviews to skip, 0 for the first page.</param>/// <param name="limit">The largest number of reviews to return, from 1 to 50.</param>/// <response code="200">One page of Reviews.</response>/// <response code="400">The Id, the offset or the limit is not valid.</response>/// <response code="500">An unexpected error occurred.</response>public static async Task<Ok<Page<ReviewEntities.Review>>> GetMovieReviews([FromRoute] Guid id,[FromServices] ISender sender,CancellationToken cancellationToken,[FromQuery] int offset = 0,[FromQuery] int limit = Paging.DefaultLimit){return TypedResults.Ok(await sender.Send(new ReviewQueries.GetReviews.GetReviewsQuery{MovieId = id,Offset = offset,Limit = limit}, cancellationToken));}Leave the
ISenderparameter undocumented on purpose. The .NET 10 XML comment generator would otherwise attach its description to the request body, which is nobody’s idea of helpful. -
Test it in
tests/Presentation.Tests.Integration/Endpoints/MovieEndpointTests.cs. Addusing ReviewEntities = Application.Reviews.Entities;next to the existing alias, then pick a movie that has reviews and ask for them.[Fact]public async Task GetMovieReviews_ShouldReturn_Ok(){// Arrangeusing var client = this.application.CreateClient();using var movieResponse = await client.GetAsync("/api/movies?limit=50");var movie = (await movieResponse.Content.ReadAsStringAsync()).Deserialize<Page<Entities.MovieSummary>>().Items.First(m => m.ReviewCount > 0);// Actusing var response = await client.GetAsync($"/api/movies/{movie.Id}/reviews?limit=50");var result = (await response.Content.ReadAsStringAsync()).Deserialize<Page<ReviewEntities.Review>>();// Assertresponse.StatusCode.ShouldBe(HttpStatusCode.OK);result.TotalCount.ShouldBe(movie.ReviewCount);result.Items.ShouldAllBe(r => r.ReviewedMovie!.Id == movie.Id);} -
Change one number.
GetOpenApiDocument_ShouldDescribe_EveryOperationintests/Presentation.Tests.Integration/OpenApi/OpenApiDocumentTests.cscounts the operations the API publishes, and there’s one more now, so make it 11. The same test checks that every operation has a summary, a sample request and a description for each parameter, which is why step 3’s comments aren’t optional either. -
Run it.
Terminal window dotnet testdotnet run --project ./src/Presentationcurl "https://localhost:7311/api/movies/cb188ef6-14e7-f85f-2f78-924c2ab26b28/reviews?limit=2"{"items": [{ "id": "45911e6f-a366-417b-1453-f34097338ee2", "stars": 5, "reviewedMovie": { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners" }, "reviewAuthor": { "id": "1cc2ad51-61c5-63ee-dd6e-15308cfe6e51", "firstName": "Caroline", "lastName": "Bins" }, "text": "Everyone involved should be very proud." },{ "id": "8832846c-4100-e92a-0b66-e59dcfde2acc", "stars": 3, "reviewedMovie": { "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners" }, "reviewAuthor": { "id": "1cc2ad51-61c5-63ee-dd6e-15308cfe6e51", "firstName": "Caroline", "lastName": "Bins" }, "text": "I laughed twice and looked at my phone once." }],"offset": 0,"limit": 2,"totalCount": 5}Caroline gave the same movie a 5 and a 3. Sample data has no continuity editor.
Open Scalar and the new endpoint is there under Movies, documented, with a working Send button. A limit of 99 comes back as a 400 Problem Details response and an unknown movie id comes back as an empty page, both before your code has to worry about it.