Add examples (#119)

<!--- Provide a general summary of your changes in the Title above -->

## Description 💬
<!--- Describe your changes in detail -->

## Motivation and Context 🥅
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here. -->

## How has this been tested? 🧪
<!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, tests ran to see how
-->
<!--- your change affects other areas of the code, etc. -->
- [x] Local build ⚒️
- [ ] Local tests 🧪
- [ ] (optional) Local run and endpoint tested in swagger 🚀

## Screenshots (if appropriate) 💻

## Types of changes 🌊
<!--- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)

## Checklist ☑️

<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
- [ ] The pull request title starts with the jira case number (when
applicable), e.g. "TEST-1234 Add some feature"
- [ ] The person responsible for following up on requested review
changes has been assigned to the pull request
- [ ] My code follows the code style of this project.
- [ ] My change requires a change to the documentation.
- [ ] I have updated the documentation accordingly.

## Highly optional checks, only use these if you have a reason to do so
✔️

- [ ] This PR changes the database so I have added the *create-diagram*
label to assist reviewers with a db diagram
- [ ] This PR changes platform or backend and I need others to be able
to test against these changes before merging to dev, so I have added the
*deploy-azure* label to deploy before merging the PR

## Checklist for the approver ✅

- [ ] I've checked the files view for spelling issues, code quality
warnings and similar
- [ ] I've waited until all checks have passed (green check/without
error)
- [ ] I've checked that only the intended files are changed

.github/actions/frontend-build/action.yml

@@ -147,4 +147,4 @@ runs:
       with:
         github-token: ${{ env.GH_TOKEN }}
         review-message: "Please take a look :eyes:"
-        tags: "TODO,FIXME,BUG"
+        tags: "TODO:,FIXME:,BUG:"

.github/workflows/backend-ci.yml

@@ -119,7 +119,7 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           review-message: "Please take a look :eyes:"
-          tags: "TODO,FIXME,BUG"
+          tags: "TODO:,FIXME:,BUG:"
 
       # # TODO: move?
       # - name: Super-linter
@@ -137,13 +137,16 @@ jobs:
 
       - name: WebApi Tests
         run: dotnet test ../../tests/backend/WebApi.Tests --no-restore --collect:"XPlat Code Coverage" --logger "trx;LogFileName=test-results.trx" /p:CollectCoverage=true /p:CoverletOutput="../../tests/backend/WebApi.Tests/TestResults/" /p:CoverletOutputFormat=cobertura
+        continue-on-error: true
 
+      #- uses: hwinther/test-reporter@dotnet-nunit # TODO: set back to original once nunit is supported: dorny/test-reporter@v1
       - uses: dorny/test-reporter@v1
+        id: test-reporter
         with:
           name: "WebApi Tests"
           path: "tests/backend/WebApi.Tests/TestResults/test-results.trx"
-          reporter: dotnet-trx
-          fail-on-error: true
+          reporter: dotnet-trx # dotnet-nunit
+          fail-on-error: false
 
       - name: Generate report for all tests
         id: reportgenerator
@@ -161,7 +164,7 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           comment-identifier: "${{ env.WORKFLOW_SHORT_NAME }}-reportgenerator"
-          comment-content: ${{ steps.reportgenerator.outputs.markdown }}
+          comment-content: ${{ steps.reportgenerator.outputs.markdown }}${{ steps.test-reporter.outputs.conclusion }}
 
       - name: Code Coverage Report
         uses: irongut/[email protected]
@@ -203,5 +206,4 @@ jobs:
           solutionWideAnalysis: true
           include: |
             **.cs
-          ignoreIssueType:
-            PropertyCanBeMadeInitOnly.Global
+          ignoreIssueType: PropertyCanBeMadeInitOnly.Global

src/backend/WebApi/Controllers/BloggingController.cs

@@ -12,9 +12,10 @@ namespace WebApi.Controllers;
 public class BloggingController(ILogger<BloggingController> logger, IBloggingRepository bloggingRepository) : ControllerBase
 {
     /// <summary>
-    ///     Get blogs
+    ///     Gets a list of all blogs.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="cancellationToken">Cancellation token to cancel the request.</param>
+    /// <returns>A list of BlogDto objects wrapped in an ActionResult.</returns>
     [HttpGet("blog", Name = "GetBlogs")]
     public async Task<ActionResult<IEnumerable<BlogDto>>> GetBlogs(CancellationToken cancellationToken)
     {
@@ -23,9 +24,11 @@ public async Task<ActionResult<IEnumerable<BlogDto>>> GetBlogs(CancellationToken
     }
 
     /// <summary>
-    ///     Get specific blog
+    ///     Gets a specific blog by ID.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="id" example="1">The ID of the blog.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the request.</param>
+    /// <returns>A single BlogDto object wrapped in an ActionResult. Returns NotFound if the blog does not exist.</returns>
     [HttpGet("blog/{id:int}", Name = "GetBlog")]
     public async Task<ActionResult<BlogDto>> GetBlog(int id, CancellationToken cancellationToken)
     {
@@ -38,9 +41,11 @@ public async Task<ActionResult<BlogDto>> GetBlog(int id, CancellationToken cance
     }
 
     /// <summary>
-    ///     Create or update blog
+    ///     Creates a new blog or updates an existing one.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="blog">The blog data transfer object</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>Returns the created or updated blog</returns>
     [HttpPost("blog", Name = "PostBlog")]
     public async Task<ActionResult<BlogDto>> PostBlog(BlogDto blog, CancellationToken cancellationToken)
     {
@@ -53,9 +58,11 @@ public async Task<ActionResult<BlogDto>> PostBlog(BlogDto blog, CancellationToke
     }
 
     /// <summary>
-    ///     Get posts related to a blog
+    ///     Gets a list of posts related to a specific blog.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="blogId" example="1">The ID of the blog</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>Returns a list of posts</returns>
     [HttpGet("blog/{blogId:int}/posts", Name = "GetPosts")]
     public async Task<ActionResult<IEnumerable<PostDto>>> GetPosts(int blogId, CancellationToken cancellationToken)
     {
@@ -64,9 +71,11 @@ public async Task<ActionResult<IEnumerable<PostDto>>> GetPosts(int blogId, Cance
     }
 
     /// <summary>
-    ///     Get specific post by id
+    ///     Gets a specific post by ID.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="id" example="1">The ID of the post</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>Returns the requested post</returns>
     [HttpGet("post/{id:int}", Name = "GetPost")]
     public async Task<ActionResult<PostDto>> GetPost(int id, CancellationToken cancellationToken)
     {
@@ -79,9 +88,11 @@ public async Task<ActionResult<PostDto>> GetPost(int id, CancellationToken cance
     }
 
     /// <summary>
-    ///     Create or update post
+    ///     Creates a new post.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="post">The post data transfer object</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>Returns the created post</returns>
     [HttpPost("post", Name = "PostPost")]
     public async Task<ActionResult<PostDto>> PostPost(PostDto post, CancellationToken cancellationToken)
     {

src/backend/WebApi/BloggingContext.cs → src/backend/WebApi/Database/BloggingContext.cs

@@ -1,7 +1,7 @@
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
 
-namespace WebApi;
+namespace WebApi.Database;
 
 /// <summary>
 ///     Represents the database context for blogging, configuring entities and their relationships.
@@ -31,11 +31,19 @@ public interface IBlog
     /// <summary>
     ///     Gets or sets the unique identifier for the blog.
     /// </summary>
+    /// <example>1</example>
     public int BlogId { get; set; }
 
+    /// <summary>
+    ///     Gets or sets the title of the blog.
+    /// </summary>
+    /// <example>My blog title</example>
+    public string Title { get; set; }
+
     /// <summary>
     ///     Gets or sets the URL of the blog.
     /// </summary>
+    /// <example>https://localhost/a-test-blog</example>
     public string Url { get; set; }
 }
 
@@ -51,6 +59,9 @@ public class Blog : IBlog
     /// <inheritdoc />
     public int BlogId { get; set; }
 
+    /// <inheritdoc />
+    public required string Title { get; set; }
+
     /// <inheritdoc />
     public required string Url { get; set; }
 }
@@ -63,6 +74,9 @@ public class BlogConfiguration : IEntityTypeConfiguration<Blog>
     /// <inheritdoc />
     public void Configure(EntityTypeBuilder<Blog> builder)
     {
+        builder.Property(static post => post.Title)
+               .HasMaxLength(500);
+
         builder.Property(static post => post.Url)
                .HasMaxLength(1000);
     }
@@ -76,21 +90,25 @@ public interface IPost
     /// <summary>
     ///     Gets or sets the unique identifier for the post.
     /// </summary>
+    /// <example>1</example>
     public int PostId { get; set; }
 
     /// <summary>
     ///     Gets or sets the title of the post.
     /// </summary>
+    /// <example>Bob Loblaw's Law Blog</example>
     public string Title { get; set; }
 
     /// <summary>
     ///     Gets or sets the content of the post.
     /// </summary>
+    /// <example>Example blog post content</example>
     public string Content { get; set; }
 
     /// <summary>
     ///     Gets or sets the unique identifier of the blog to which the post belongs.
     /// </summary>
+    /// <example>1</example>
     public int BlogId { get; set; }
 }
 
@@ -102,6 +120,7 @@ public class Post : IPost
     ///     Gets or sets the blog to which the post belongs.
     /// </summary>
     public Blog? Blog { get; set; }
+
     /// <inheritdoc />
     public required int BlogId { get; set; }
 

src/backend/WebApi/Entities/BlogDto.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using WebApi.Database;
 
 namespace WebApi.Entities;
 
@@ -10,12 +11,21 @@ public record BlogDto : IBlog, IValidatableObject
     /// <inheritdoc />
     public int BlogId { get; set; }
 
+    /// <inheritdoc />
+    public required string Title { get; set; }
+
     /// <inheritdoc />
     public required string Url { get; set; }
 
     /// <inheritdoc />
     public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
     {
+        if (string.IsNullOrEmpty(Title))
+            yield return new ValidationResult($"{nameof(Title)} must be set");
+
+        if (Title.Length > 1000)
+            yield return new ValidationResult($"{nameof(Title)} is longer than the maximum amount of characters (500)");
+
         if (string.IsNullOrEmpty(Url))
             yield return new ValidationResult($"{nameof(Url)} must be set");
 
@@ -39,6 +49,7 @@ public static BlogDto FromEntity(Blog blog) =>
         new()
         {
             BlogId = blog.BlogId,
+            Title = blog.Title,
             Url = blog.Url
         };
 }

src/backend/WebApi/Entities/PostDto.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using WebApi.Database;
 
 namespace WebApi.Entities;