OpenAPI Controllers Sample with XML Comments

.gitignore

@@ -9,7 +9,6 @@
 
 _build/
 _site/
-Properties/
 
 # See #577
 # Use git add -f to force override .sln when required. Not needed in most cases.
@@ -227,3 +226,6 @@ __pycache__/
 
 # Windows thumbnail cache files
 Thumbs.db
+
+# Rider
+.idea/

aspnetcore/fundamentals/openapi/samples/10.x/aspnet-openapi-xml-controllers/api/AdditionalFiles.xml

@@ -0,0 +1,8 @@
+<ItemGroup>
+  <PackageReference Include="Some.Package" Version="10.0.0"
+                    GeneratePathProperty="true" />
+</ItemGroup>
+
+<ItemGroup>
+  <AdditionalFiles Include="$(PkgSome_Package)/lib/net10.0/Some.Package.xml" />
+</ItemGroup>

aspnetcore/fundamentals/openapi/samples/10.x/aspnet-openapi-xml-controllers/api/Api-remove.csproj.xml

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.2.25161.17" />
+    <PackageReference Include="Scalar.AspNetCore" Version="2.0.30" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\models\Models.csproj" />
+  </ItemGroup>
+
+  <Target Name="DisableCompileTimeOpenApiXmlGenerator" BeforeTargets="CoreCompile">
+    <ItemGroup>
+      <Analyzer Remove="$(PkgMicrosoft_AspNetCore_OpenApi)/analyzers/dotnet/cs/Microsoft.AspNetCore.OpenApi.SourceGenerators.dll" />
+    </ItemGroup>
+  </Target>
+
+</Project>

aspnetcore/fundamentals/openapi/samples/10.x/aspnet-openapi-xml-controllers/api/Api.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.3" />
+    <PackageReference Include="Scalar.AspNetCore" Version="2.0.30" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\models\Models.csproj" />
+  </ItemGroup>
+
+</Project>

aspnetcore/fundamentals/openapi/samples/10.x/aspnet-openapi-xml-controllers/api/Api.http

@@ -0,0 +1,73 @@
+@Api_HostAddress = http://localhost:5052
+
+GET {{Api_HostAddress}}/weatherforecast/
+Accept: application/json
+
+### Project Board Endpoints ###
+
+### Get all project boards
+GET {{Api_HostAddress}}/api/projectboards
+Accept: application/json
+
+### Get project board by ID
+GET {{Api_HostAddress}}/api/projectboards/1
+Accept: application/json
+
+### Create a new project board
+POST {{Api_HostAddress}}/api/projectboards
+Content-Type: application/json
+
+{
+  "name": "Website Redesign",
+  "description": "Tasks for redesigning the company website"
+}
+
+### Update a project board
+PUT {{Api_HostAddress}}/api/projectboards/1
+Content-Type: application/json
+
+{
+  "name": "Website Redesign v2",
+  "description": "Updated tasks for redesigning the company website"
+}
+
+### Delete a project board
+DELETE {{Api_HostAddress}}/api/projectboards/1
+
+
+### Todo Endpoints ###
+
+### Get all todos for a project board
+GET {{Api_HostAddress}}/api/projectboards/1/todos
+Accept: application/json
+
+### Get a specific todo by ID
+GET {{Api_HostAddress}}/api/projectboards/1/todos/1
+Accept: application/json
+
+### Create a new todo
+POST {{Api_HostAddress}}/api/projectboards/1/todos
+Content-Type: application/json
+
+{
+  "title": "Design new homepage",
+  "description": "Create wireframes for the new homepage design",
+  "isComplete": false,
+  "priority": 2,
+  "dueDate": "2025-03-20T00:00:00Z"
+}
+
+### Update a todo
+PUT {{Api_HostAddress}}/api/projectboards/1/todos/1
+Content-Type: application/json
+
+{
+  "title": "Design new homepage with feedback",
+  "description": "Update wireframes based on stakeholder feedback",
+  "isComplete": true,
+  "priority": 3,
+  "dueDate": "2025-03-25T00:00:00Z"
+}
+
+### Delete a todo
+DELETE {{Api_HostAddress}}/api/projectboards/1/todos/1

aspnetcore/fundamentals/openapi/samples/10.x/aspnet-openapi-xml-controllers/api/Controllers/ProjectBoardsController.cs

@@ -0,0 +1,119 @@
+using Microsoft.AspNetCore.Mvc;
+using Models;
+
+namespace Api.Controllers;
+
+/// <summary>
+/// API controller for managing project boards.
+/// </summary>
+[ApiController]
+[Route("api/[controller]")]
+[Tags("Project Boards")]
+public class ProjectBoardsController : ControllerBase
+{
+    // In-memory storage for demo purposes
+    internal static readonly List<ProjectBoard> Boards = new();
+    private static int _nextBoardId = 1;
+
+    /// <summary>
+    /// Retrieves all project boards.
+    /// </summary>
+    /// <returns>A collection of all project boards.</returns>
+    /// <response code="200">Returns the list of project boards.</response>
+    [HttpGet]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    public ActionResult<IEnumerable<ProjectBoard>> GetAllProjectBoards()
+    {
+        return Ok(Boards);
+    }
+
+    // <snippet_1>
+    /// <summary>
+    /// Retrieves a specific project board by ID.
+    /// </summary>
+    /// <param name="id">The ID of the project board to retrieve.</param>
+    /// <returns>The requested project board.</returns>
+    /// <response code="200">Returns the requested project board.</response>
+    /// <response code="404">If the project board is not found.</response>
+    [HttpGet("{id}")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public ActionResult<ProjectBoard> GetProjectBoardById(int id)
+    {
+        var board = Boards.FirstOrDefault(b => b.Id == id);
+        if (board == null)
+        {
+            return NotFound();
+        }
+        return Ok(board);
+    }
+    // </snippet_1>
+
+    /// <summary>
+    /// Creates a new project board.
+    /// </summary>
+    /// <param name="board">The project board to create.</param>
+    /// <returns>The newly created project board.</returns>
+    /// <response code="201">Returns the newly created project board.</response>
+    /// <response code="400">If the project board data is invalid.</response>
+    [HttpPost]
+    [ProducesResponseType(StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public ActionResult<ProjectBoard> CreateProjectBoard(ProjectBoard board)
+    {
+        board.Id = _nextBoardId++;
+        board.CreatedAt = DateTime.UtcNow;
+        Boards.Add(board);
+
+        return CreatedAtAction(nameof(GetProjectBoardById), new { id = board.Id }, board);
+    }
+
+    /// <summary>
+    /// Updates an existing project board.
+    /// </summary>
+    /// <param name="id">The ID of the project board to update.</param>
+    /// <param name="updatedBoard">The updated project board data.</param>
+    /// <returns>No content if successful.</returns>
+    /// <response code="204">If the update was successful.</response>
+    /// <response code="400">If the project board data is invalid.</response>
+    /// <response code="404">If the project board is not found.</response>
+    [HttpPut("{id}")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult UpdateProjectBoard(int id, ProjectBoard updatedBoard)
+    {
+        var board = Boards.FirstOrDefault(b => b.Id == id);
+        if (board == null)
+        {
+            return NotFound();
+        }
+
+        board.Name = updatedBoard.Name;
+        board.Description = updatedBoard.Description;
+
+        return NoContent();
+    }
+
+    /// <summary>
+    /// Deletes a project board.
+    /// </summary>
+    /// <param name="id">The ID of the project board to delete.</param>
+    /// <returns>No content if successful.</returns>
+    /// <response code="204">If the deletion was successful.</response>
+    /// <response code="404">If the project board is not found.</response>
+    [HttpDelete("{id}")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult DeleteProjectBoard(int id)
+    {
+        var board = Boards.FirstOrDefault(b => b.Id == id);
+        if (board == null)
+        {
+            return NotFound();
+        }
+
+        Boards.Remove(board);
+        return NoContent();
+    }
+}