From d8633f929896ddb56af5520eca01472d922ad263 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Mon, 2 Sep 2024 22:22:32 -0400 Subject: [PATCH] Add Endpoint Operation IDs (#243) * Add endpoint operation IDs. * Update swagger packages. --- .../Controllers/AccountController.cs | 14 +++++++------- .../Controllers/CategoriesController.cs | 4 ++-- .../Controllers/LeaderboardsController.cs | 8 ++++---- .../Controllers/RunsController.cs | 5 +++-- .../Controllers/UsersController.cs | 5 +++-- LeaderboardBackend/LeaderboardBackend.csproj | 6 +++--- LeaderboardBackend/openapi.json | 19 +++++++++++++++++++ 7 files changed, 41 insertions(+), 20 deletions(-) diff --git a/LeaderboardBackend/Controllers/AccountController.cs b/LeaderboardBackend/Controllers/AccountController.cs index 9ea54c78..ddc3edae 100644 --- a/LeaderboardBackend/Controllers/AccountController.cs +++ b/LeaderboardBackend/Controllers/AccountController.cs @@ -24,7 +24,7 @@ public AccountController(IUserService userService) [AllowAnonymous] [FeatureGate(Features.ACCOUNT_REGISTRATION)] [HttpPost("register")] - [SwaggerOperation("Registers a new User.")] + [SwaggerOperation("Registers a new User.", OperationId = "register")] [SwaggerResponse(201, "The `User` was registered and returned successfully.")] [SwaggerResponse( 409, @@ -96,7 +96,7 @@ [FromServices] IAccountConfirmationService confirmationService [AllowAnonymous] [FeatureGate(Features.LOGIN)] [HttpPost("/login")] - [SwaggerOperation("Logs a User in.")] + [SwaggerOperation("Logs a User in.", OperationId = "login")] [SwaggerResponse( 200, "The `User` was logged in successfully. A `LoginResponse` is returned, containing a token.", @@ -138,7 +138,7 @@ public async Task> Login( [Authorize] [HttpPost("confirm")] - [SwaggerOperation("Resends the account confirmation link.")] + [SwaggerOperation("Resends the account confirmation link.", OperationId = "resendConfirmationEmail")] [SwaggerResponse(200, "A new confirmation link was generated.")] [SwaggerResponse(401)] [SwaggerResponse(409, "The `User`'s account has already been confirmed.")] @@ -171,7 +171,7 @@ [FromServices] IAccountConfirmationService confirmationService [AllowAnonymous] [HttpPost("recover")] - [SwaggerOperation("Sends an account recovery email.")] + [SwaggerOperation("Sends an account recovery email.", OperationId = "sendRecoveryEmail")] [SwaggerResponse(200, "This endpoint returns 200 OK regardless of whether the email was sent successfully or not.")] [FeatureGate(Features.ACCOUNT_RECOVERY)] public async Task RecoverAccount( @@ -197,7 +197,7 @@ public async Task RecoverAccount( [AllowAnonymous] [HttpPut("confirm/{id}")] - [SwaggerOperation("Confirms a user account.")] + [SwaggerOperation("Confirms a user account.", OperationId = "confirmAccount")] [SwaggerResponse(200, "The account was confirmed successfully.")] [SwaggerResponse(404, "The token provided was invalid or expired.")] [SwaggerResponse(409, "the user's account was either already confirmed or banned.")] @@ -219,7 +219,7 @@ [FromServices] IAccountConfirmationService confirmationService [AllowAnonymous] [HttpGet("recover/{id}")] - [SwaggerOperation("Tests an account recovery token for validity.")] + [SwaggerOperation("Tests an account recovery token for validity.", OperationId = "testRecoveryToken")] [SwaggerResponse(200, "The token provided is valid.")] [SwaggerResponse(404, "The token provided is invalid or expired, or the user is banned.")] [FeatureGate(Features.ACCOUNT_RECOVERY)] @@ -242,7 +242,7 @@ [FromServices] IAccountRecoveryService recoveryService [AllowAnonymous] [FeatureGate(Features.ACCOUNT_RECOVERY)] [HttpPost("recover/{id}")] - [SwaggerOperation("Recover the user's account by resetting their password to a new value.")] + [SwaggerOperation("Recover the user's account by resetting their password to a new value.", OperationId = "changePassword")] [SwaggerResponse(200, "The user's password was reset successfully.")] [SwaggerResponse(403, "The user is banned.")] [SwaggerResponse(404, "The token provided is invalid or expired.")] diff --git a/LeaderboardBackend/Controllers/CategoriesController.cs b/LeaderboardBackend/Controllers/CategoriesController.cs index 4b58c1d4..7c64fd42 100644 --- a/LeaderboardBackend/Controllers/CategoriesController.cs +++ b/LeaderboardBackend/Controllers/CategoriesController.cs @@ -20,7 +20,7 @@ public CategoriesController(ICategoryService categoryService) [AllowAnonymous] [HttpGet("api/category/{id}")] - [SwaggerOperation("Gets a Category by its ID.")] + [SwaggerOperation("Gets a Category by its ID.", OperationId = "getCategory")] [SwaggerResponse(200)] [SwaggerResponse(404)] public async Task> GetCategory(long id) @@ -37,7 +37,7 @@ public async Task> GetCategory(long id) [Authorize(Policy = UserTypes.ADMINISTRATOR)] [HttpPost("categories/create")] - [SwaggerOperation("Creates a new Category. This request is restricted to Moderators.")] + [SwaggerOperation("Creates a new Category. This request is restricted to Moderators.", OperationId = "createCategory")] [SwaggerResponse(201)] [SwaggerResponse(403)] [SwaggerResponse(422, Type = typeof(ValidationProblemDetails))] diff --git a/LeaderboardBackend/Controllers/LeaderboardsController.cs b/LeaderboardBackend/Controllers/LeaderboardsController.cs index 7e91e053..55ec38bc 100644 --- a/LeaderboardBackend/Controllers/LeaderboardsController.cs +++ b/LeaderboardBackend/Controllers/LeaderboardsController.cs @@ -20,7 +20,7 @@ public LeaderboardsController(ILeaderboardService leaderboardService) [AllowAnonymous] [HttpGet("api/leaderboard/{id:long}")] - [SwaggerOperation("Gets a leaderboard by its ID.")] + [SwaggerOperation("Gets a leaderboard by its ID.", OperationId = "getLeaderboard")] [SwaggerResponse(200)] [SwaggerResponse(404)] public async Task> GetLeaderboard(long id) @@ -37,7 +37,7 @@ public async Task> GetLeaderboard(long id) [AllowAnonymous] [HttpGet("api/leaderboard")] - [SwaggerOperation("Gets a Leaderboard by its slug.")] + [SwaggerOperation("Gets a Leaderboard by its slug.", OperationId = "getLeaderboardBySlug")] [SwaggerResponse(200)] [SwaggerResponse(404)] public async Task> GetLeaderboardBySlug([FromQuery, SwaggerParameter(Required = true)] string slug) @@ -54,7 +54,7 @@ public async Task> GetLeaderboardBySlug([From [AllowAnonymous] [HttpGet("api/leaderboards")] - [SwaggerOperation("Gets leaderboards by their IDs.")] + [SwaggerOperation("Gets leaderboards by their IDs.", OperationId = "getLeaderboards")] [SwaggerResponse(200)] public async Task>> GetLeaderboards( [FromQuery] long[] ids @@ -66,7 +66,7 @@ [FromQuery] long[] ids [Authorize(Policy = UserTypes.ADMINISTRATOR)] [HttpPost("leaderboards/create")] - [SwaggerOperation("Creates a new leaderboard. This request is restricted to Administrators.")] + [SwaggerOperation("Creates a new leaderboard. This request is restricted to Administrators.", OperationId = "createLeaderboard")] [SwaggerResponse(201)] [SwaggerResponse(401)] [SwaggerResponse(403, "The requesting `User` is unauthorized to create `Leaderboard`s.")] diff --git a/LeaderboardBackend/Controllers/RunsController.cs b/LeaderboardBackend/Controllers/RunsController.cs index aefdcb9c..c11cf3d5 100644 --- a/LeaderboardBackend/Controllers/RunsController.cs +++ b/LeaderboardBackend/Controllers/RunsController.cs @@ -18,7 +18,7 @@ IUserService userService { [AllowAnonymous] [HttpGet("api/run/{id}")] - [SwaggerOperation("Gets a Run by its ID.")] + [SwaggerOperation("Gets a Run by its ID.", OperationId = "getRun")] [SwaggerResponse(200)] [SwaggerResponse(404)] public async Task> GetRun(Guid id) @@ -35,7 +35,7 @@ public async Task> GetRun(Guid id) [Authorize] [HttpPost("runs/create")] - [SwaggerOperation("Creates a new Run.")] + [SwaggerOperation("Creates a new Run.", OperationId = "createRun")] [SwaggerResponse(201)] [SwaggerResponse(401)] [SwaggerResponse(403)] @@ -64,6 +64,7 @@ public async Task CreateRun([FromBody] CreateRunRequest request) } [HttpGet("/api/run/{id}/category")] + [SwaggerOperation("Gets the category a run belongs to.", OperationId = "getRunCategory")] [SwaggerResponse(200)] [SwaggerResponse(404)] public async Task> GetCategoryForRun(Guid id) diff --git a/LeaderboardBackend/Controllers/UsersController.cs b/LeaderboardBackend/Controllers/UsersController.cs index f1f48fbe..20c57e5d 100644 --- a/LeaderboardBackend/Controllers/UsersController.cs +++ b/LeaderboardBackend/Controllers/UsersController.cs @@ -20,7 +20,7 @@ public UsersController(IUserService userService) [AllowAnonymous] [HttpGet("api/user/{id:guid}")] - [SwaggerOperation("Gets a User by their ID.")] + [SwaggerOperation("Gets a User by their ID.", OperationId = "getUser")] [SwaggerResponse(200, "The `User` was found and returned successfully.")] [SwaggerResponse(404, "No `User` with the requested ID could be found.")] public async Task> GetUserById( @@ -45,7 +45,8 @@ public async Task> GetUserById( Call this method with the 'Authorization' header. A valid JWT bearer token must be passed. Example: `{ 'Authorization': 'Bearer JWT' }`. - """ + """, + OperationId = "me" )] [SwaggerResponse(200, "The `User` was found and returned successfully.")] [SwaggerResponse(401, "An invalid JWT was passed in.")] diff --git a/LeaderboardBackend/LeaderboardBackend.csproj b/LeaderboardBackend/LeaderboardBackend.csproj index 16811d88..4e493cad 100644 --- a/LeaderboardBackend/LeaderboardBackend.csproj +++ b/LeaderboardBackend/LeaderboardBackend.csproj @@ -49,9 +49,9 @@ - - - + + + diff --git a/LeaderboardBackend/openapi.json b/LeaderboardBackend/openapi.json index f08a0d34..44371ecf 100644 --- a/LeaderboardBackend/openapi.json +++ b/LeaderboardBackend/openapi.json @@ -11,6 +11,7 @@ "Account" ], "summary": "Registers a new User.", + "operationId": "register", "requestBody": { "description": "The `RegisterRequest` instance from which to register the `User`.", "content": { @@ -75,6 +76,7 @@ "Account" ], "summary": "Logs a User in.", + "operationId": "login", "requestBody": { "description": "The `LoginRequest` instance with which to perform the login.", "content": { @@ -138,6 +140,7 @@ "Account" ], "summary": "Resends the account confirmation link.", + "operationId": "resendConfirmationEmail", "responses": { "400": { "description": "Bad Request", @@ -170,6 +173,7 @@ "Account" ], "summary": "Sends an account recovery email.", + "operationId": "sendRecoveryEmail", "requestBody": { "description": "The account recovery request.", "content": { @@ -206,6 +210,7 @@ "Account" ], "summary": "Confirms a user account.", + "operationId": "confirmAccount", "parameters": [ { "name": "id", @@ -250,6 +255,7 @@ "Account" ], "summary": "Tests an account recovery token for validity.", + "operationId": "testRecoveryToken", "parameters": [ { "name": "id", @@ -289,6 +295,7 @@ "Account" ], "summary": "Recover the user's account by resetting their password to a new value.", + "operationId": "changePassword", "parameters": [ { "name": "id", @@ -357,6 +364,7 @@ "Categories" ], "summary": "Gets a Category by its ID.", + "operationId": "getCategory", "parameters": [ { "name": "id", @@ -404,6 +412,7 @@ "Categories" ], "summary": "Creates a new Category. This request is restricted to Moderators.", + "operationId": "createCategory", "requestBody": { "content": { "application/json": { @@ -459,6 +468,7 @@ "Leaderboards" ], "summary": "Gets a leaderboard by its ID.", + "operationId": "getLeaderboard", "parameters": [ { "name": "id", @@ -506,6 +516,7 @@ "Leaderboards" ], "summary": "Gets a Leaderboard by its slug.", + "operationId": "getLeaderboardBySlug", "parameters": [ { "name": "slug", @@ -552,6 +563,7 @@ "Leaderboards" ], "summary": "Gets leaderboards by their IDs.", + "operationId": "getLeaderboards", "parameters": [ { "name": "ids", @@ -601,6 +613,7 @@ "Leaderboards" ], "summary": "Creates a new leaderboard. This request is restricted to Administrators.", + "operationId": "createLeaderboard", "requestBody": { "content": { "application/json": { @@ -659,6 +672,7 @@ "Runs" ], "summary": "Gets a Run by its ID.", + "operationId": "getRun", "parameters": [ { "name": "id", @@ -716,6 +730,7 @@ "Runs" ], "summary": "Creates a new Run.", + "operationId": "createRun", "requestBody": { "content": { "application/json": { @@ -766,6 +781,8 @@ "tags": [ "Runs" ], + "summary": "Gets the category a run belongs to.", + "operationId": "getRunCategory", "parameters": [ { "name": "id", @@ -813,6 +830,7 @@ "Users" ], "summary": "Gets a User by their ID.", + "operationId": "getUser", "parameters": [ { "name": "id", @@ -862,6 +880,7 @@ ], "summary": "Gets the currently logged-in User.", "description": "Call this method with the 'Authorization' header. A valid JWT bearer token must be\npassed.\nExample: `{ 'Authorization': 'Bearer JWT' }`.", + "operationId": "me", "responses": { "400": { "description": "Bad Request",