refactor: add api versioned endpoints

This commit is contained in:
Oliver Booth 2024-03-02 03:46:29 +00:00
parent e5eeb5eaa2
commit 25a73bce0f
Signed by: oliverbooth
GPG Key ID: E60B570D1B7557B5
7 changed files with 220 additions and 9 deletions

View File

@ -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;
}
}

View File

@ -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
}
};
}
}

View File

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

View File

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

View File

@ -27,8 +27,9 @@
</PropertyGroup> </PropertyGroup>
<ItemGroup> <ItemGroup>
<PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.0.0"/>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.2"/> <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>
<ItemGroup> <ItemGroup>

View File

@ -1,6 +1,10 @@
using Asp.Versioning; using Asp.Versioning;
using Asp.Versioning.ApiExplorer;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using OliverBooth.Api;
using OliverBooth.Common.Extensions; using OliverBooth.Common.Extensions;
using Serilog; using Serilog;
using Swashbuckle.AspNetCore.SwaggerGen;
Log.Logger = new LoggerConfiguration() Log.Logger = new LoggerConfiguration()
.WriteTo.Console() .WriteTo.Console()
@ -23,17 +27,34 @@ builder.Services.AddCors(options =>
builder.Services.AddCommonServices(); builder.Services.AddCommonServices();
builder.Services.AddEndpointsApiExplorer(); 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.AddControllers();
builder.Services.AddRouting(options => options.LowercaseUrls = true); builder.Services.AddRouting(options => options.LowercaseUrls = true);
builder.Services.AddApiVersioning(options => builder.Services.AddApiVersioning(options =>
{ {
options.AssumeDefaultVersionWhenUnspecified = true; options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1); options.DefaultApiVersion = new ApiVersion(2);
options.ReportApiVersions = true; options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader(); options.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
}); });
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();
if (builder.Environment.IsProduction()) if (builder.Environment.IsProduction())
{ {
builder.WebHost.AddCertificateFromEnvironment(2844, 5048); builder.WebHost.AddCertificateFromEnvironment(2844, 5048);
@ -44,7 +65,15 @@ WebApplication app = builder.Build();
if (app.Environment.IsDevelopment()) if (app.Environment.IsDevelopment())
{ {
app.UseSwagger(); 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(); app.UseHttpsRedirection();

View File

@ -3,7 +3,7 @@ import Author from "./Author";
class API { class API {
private static readonly BLOG_URL: string = "/blog"; 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 AUTHOR_URL: string = "/author";
private static readonly POST_URL: string = "/post"; private static readonly POST_URL: string = "/post";