refactor: add api versioned endpoints

OliverBooth.Api/ConfigureSwaggerOptions.cs

@@ -0,0 +1,40 @@
+using Asp.Versioning.ApiExplorer;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace OliverBooth.Api;
+
+internal sealed class ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)
+    : IConfigureNamedOptions<SwaggerGenOptions>
+{
+    public void Configure(SwaggerGenOptions options)
+    {
+        foreach (var description in provider.ApiVersionDescriptions)
+        {
+            options.SwaggerDoc(description.GroupName, CreateVersionInfo(description));
+        }
+    }
+
+    public void Configure(string? name, SwaggerGenOptions options)
+    {
+        Configure(options);
+    }
+
+    private OpenApiInfo CreateVersionInfo(
+        ApiVersionDescription description)
+    {
+        var info = new OpenApiInfo
+        {
+            Title = "api.oliverbooth.dev",
+            Version = description.ApiVersion.ToString()
+        };
+
+        if (description.IsDeprecated)
+        {
+            info.Description += " This API version has been deprecated.";
+        }
+
+        return info;
+    }
+}

OliverBooth.Api/Controllers/v1/Blog/BlogController.cs

@@ -0,0 +1,141 @@
+using Asp.Versioning;
+using Humanizer;
+using Microsoft.AspNetCore.Mvc;
+using OliverBooth.Api.Data;
+using OliverBooth.Common.Data.Blog;
+using OliverBooth.Common.Data.Web.Users;
+using OliverBooth.Common.Services;
+
+namespace OliverBooth.Api.Controllers.v1.Blog;
+
+[ApiController]
+[Route("blog")]
+[Produces("application/json")]
+[ApiVersion(1)]
+[Obsolete("API v1 is deprecated and will be removed in future. Use /v2")]
+public sealed class BlogController : ControllerBase
+{
+    private readonly IBlogPostService _blogPostService;
+    private readonly IUserService _userService;
+
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="BlogController" /> class.
+    /// </summary>
+    /// <param name="blogPostService">The <see cref="IBlogPostService" />.</param>
+    /// <param name="userService">The <see cref="IUserService" />.</param>
+    public BlogController(IBlogPostService blogPostService, IUserService userService)
+    {
+        _blogPostService = blogPostService;
+        _userService = userService;
+    }
+
+    /// <summary>
+    ///     Returns the number of publicly published blog posts.
+    /// </summary>
+    /// <returns>The number of publicly published blog posts.</returns>
+    [HttpGet("count")]
+    [EndpointDescription("Returns the number of publicly published blog posts.")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    public IActionResult Count()
+    {
+        return Ok(new { count = _blogPostService.GetBlogPostCount() });
+    }
+
+    /// <summary>
+    ///     Returns a collection of all blog posts on the specified page.
+    /// </summary>
+    /// <param name="page">The page number.</param>
+    /// <returns>An array of <see cref="IBlogPost" /> objects.</returns>
+    [HttpGet("posts/{page:int?}")]
+    [EndpointDescription("Returns a collection of all blog posts on the specified page.")]
+    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(BlogPost[]))]
+    public IActionResult GetAllBlogPosts(int page = 0)
+    {
+        const int itemsPerPage = 10;
+        IReadOnlyList<IBlogPost> allPosts = _blogPostService.GetBlogPosts(page, itemsPerPage);
+        return Ok(allPosts.Select(post => CreatePostObject(post)));
+    }
+
+    /// <summary>
+    ///     Returns a collection of all blog posts which contain the specified tag on the specified page.
+    /// </summary>
+    /// <param name="tag">The tag for which to search.</param>
+    /// <param name="page">The page number.</param>
+    /// <returns>An array of <see cref="IBlogPost" /> objects.</returns>
+    [HttpGet("posts/tagged/{tag}/{page:int?}")]
+    [EndpointDescription("Returns a collection of all blog posts which contain the specified tag on the specified page.")]
+    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(BlogPost[]))]
+    public IActionResult GetTaggedBlogPosts(string tag, int page = 0)
+    {
+        const int itemsPerPage = 10;
+        tag = tag.Replace('-', ' ').ToLowerInvariant();
+
+        IReadOnlyList<IBlogPost> allPosts = _blogPostService.GetBlogPosts(page, itemsPerPage);
+        allPosts = allPosts.Where(post => post.Tags.Contains(tag)).ToList();
+        return Ok(allPosts.Select(post => CreatePostObject(post)));
+    }
+
+    /// <summary>
+    ///     Returns an object representing the author with the specified ID.
+    /// </summary>
+    /// <param name="id">The ID of the author.</param>
+    /// <returns>An object representing the author.</returns>
+    [HttpGet("author/{id:guid}")]
+    [EndpointDescription("Returns an object representing the author with the specified ID.")]
+    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Author))]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult GetAuthor(Guid id)
+    {
+        if (!_userService.TryGetUser(id, out IUser? author)) return NotFound();
+
+        return Ok(new
+        {
+            id = author.Id,
+            name = author.DisplayName,
+            avatarUrl = author.AvatarUrl,
+        });
+    }
+
+    /// <summary>
+    ///     Returns an object representing the blog post with the specified ID.
+    /// </summary>
+    /// <param name="id">The ID of the blog post.</param>
+    /// <returns>An object representing the blog post.</returns>
+    [HttpGet("post/{id:guid?}")]
+    [EndpointDescription("Returns an object representing the blog post with the specified ID.")]
+    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(BlogPost))]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public IActionResult GetPost(Guid id)
+    {
+        if (!_blogPostService.TryGetPost(id, out IBlogPost? post)) return NotFound();
+        return Ok(CreatePostObject(post, true));
+    }
+
+    private object CreatePostObject(IBlogPost post, bool includeContent = false)
+    {
+        return new
+        {
+            id = post.Id,
+            commentsEnabled = post.EnableComments,
+            identifier = post.GetDisqusIdentifier(),
+            author = post.Author.Id,
+            title = post.Title,
+            published = post.Published.ToUnixTimeSeconds(),
+            updated = post.Updated?.ToUnixTimeSeconds(),
+            formattedPublishDate = post.Published.ToString("dddd, d MMMM yyyy HH:mm"),
+            formattedUpdateDate = post.Updated?.ToString("dddd, d MMMM yyyy HH:mm"),
+            humanizedTimestamp = post.Updated?.Humanize() ?? post.Published.Humanize(),
+            excerpt = _blogPostService.RenderExcerpt(post, out bool trimmed),
+            content = includeContent ? _blogPostService.RenderPost(post) : null,
+            trimmed,
+            tags = post.Tags.Select(t => t.Replace(' ', '-')),
+            url = new
+            {
+                year = post.Published.ToString("yyyy"),
+                month = post.Published.ToString("MM"),
+                day = post.Published.ToString("dd"),
+                slug = post.Slug
+            }
+        };
+    }
+}

OliverBooth.Api/Controllers/v2/Blog/AuthorController.cs

@@ -4,7 +4,7 @@ using OliverBooth.Api.Data;
 using OliverBooth.Common.Data.Web.Users;
 using OliverBooth.Common.Services;
 
-namespace OliverBooth.Api.Controllers.Blog;
+namespace OliverBooth.Api.Controllers.v2.Blog;
 
 /// <summary>
 ///     Represents an API controller which allows reading authors of blog posts.
@@ -12,7 +12,7 @@ namespace OliverBooth.Api.Controllers.Blog;
 [ApiController]
 [Route("v{version:apiVersion}/blog/author")]
 [Produces("application/json")]
-[ApiVersion(1)]
+[ApiVersion(2)]
 public sealed class AuthorController : ControllerBase
 {
     private readonly IUserService _userService;

OliverBooth.Api/Controllers/v2/Blog/PostController.cs

@@ -4,7 +4,7 @@ using OliverBooth.Api.Data;
 using OliverBooth.Common.Data.Blog;
 using OliverBooth.Common.Services;
 
-namespace OliverBooth.Api.Controllers.Blog;
+namespace OliverBooth.Api.Controllers.v2.Blog;
 
 /// <summary>
 ///     Represents an API controller which allows reading and writing of blog posts.
@@ -12,7 +12,7 @@ namespace OliverBooth.Api.Controllers.Blog;
 [ApiController]
 [Route("v{version:apiVersion}/blog/post")]
 [Produces("application/json")]
-[ApiVersion(1)]
+[ApiVersion(2)]
 public sealed class PostController : ControllerBase
 {
     private const int ItemsPerPage = 10;

OliverBooth.Api/OliverBooth.Api.csproj

@@ -27,8 +27,9 @@
     </PropertyGroup>
 
     <ItemGroup>
+        <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.0.0"/>
         <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.2"/>
-        <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0"/>
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0"/>
     </ItemGroup>
 
     <ItemGroup>

OliverBooth.Api/Program.cs

@@ -1,6 +1,10 @@
 using Asp.Versioning;
+using Asp.Versioning.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using OliverBooth.Api;
 using OliverBooth.Common.Extensions;
 using Serilog;
+using Swashbuckle.AspNetCore.SwaggerGen;
 
 Log.Logger = new LoggerConfiguration()
     .WriteTo.Console()
@@ -23,17 +27,34 @@ builder.Services.AddCors(options =>
 
 builder.Services.AddCommonServices();
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen();
+builder.Services.AddSwaggerGen(options => options.ResolveConflictingActions(resolver =>
+{
+    foreach (ApiDescription description in resolver)
+    {
+        if (description.GetApiVersion()?.MajorVersion == 2)
+        {
+            return description;
+        }
+    }
+
+    return null;
+}));
 builder.Services.AddControllers();
 builder.Services.AddRouting(options => options.LowercaseUrls = true);
 builder.Services.AddApiVersioning(options =>
 {
     options.AssumeDefaultVersionWhenUnspecified = true;
-    options.DefaultApiVersion = new ApiVersion(1);
+    options.DefaultApiVersion = new ApiVersion(2);
     options.ReportApiVersions = true;
     options.ApiVersionReader = new UrlSegmentApiVersionReader();
+}).AddApiExplorer(options =>
+{
+    options.GroupNameFormat = "'v'VVV";
+    options.SubstituteApiVersionInUrl = true;
 });
 
+builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();
+
 if (builder.Environment.IsProduction())
 {
     builder.WebHost.AddCertificateFromEnvironment(2844, 5048);
@@ -44,7 +65,15 @@ WebApplication app = builder.Build();
 if (app.Environment.IsDevelopment())
 {
     app.UseSwagger();
-    app.UseSwaggerUI();
+    app.UseSwaggerUI(options =>
+    {
+        var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
+        foreach (ApiVersionDescription description in provider.ApiVersionDescriptions)
+        {
+            var url = $"/swagger/{description.GroupName}/swagger.json";
+            options.SwaggerEndpoint(url, description.GroupName.ToUpperInvariant());
+        }
+    });
 }
 
 app.UseHttpsRedirection();

src/ts/app/API.ts

@@ -3,7 +3,7 @@ import Author from "./Author";
 
 class API {
     private static readonly BLOG_URL: string = "/blog";
-    private static readonly BASE_URL: string = `https://localhost:2840/v1${API.BLOG_URL}`;
+    private static readonly BASE_URL: string = `https://localhost:2840/v2${API.BLOG_URL}`;
     private static readonly AUTHOR_URL: string = "/author";
     private static readonly POST_URL: string = "/post";