Add Endpoint Operation IDs (leaderboardsgg#243)

* Add endpoint operation IDs. * Update swagger packages.
TheTedder · Sep 3, 2024 · d8633f9 · d8633f9
1 parent b677869
commit d8633f9
Show file tree

Hide file tree

Showing 7 changed files with 41 additions and 20 deletions.
diff --git 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<ActionResult<LoginResponse>> 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<ActionResult> RecoverAccount(
@@ -197,7 +197,7 @@ public async Task<ActionResult> 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
@@ -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<ActionResult<CategoryViewModel>> GetCategory(long id)
@@ -37,7 +37,7 @@ public async Task<ActionResult<CategoryViewModel>> 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
@@ -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<ActionResult<LeaderboardViewModel>> GetLeaderboard(long id)
@@ -37,7 +37,7 @@ public async Task<ActionResult<LeaderboardViewModel>> 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<ActionResult<LeaderboardViewModel>> GetLeaderboardBySlug([FromQuery, SwaggerParameter(Required = true)] string slug)
@@ -54,7 +54,7 @@ public async Task<ActionResult<LeaderboardViewModel>> 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<ActionResult<List<LeaderboardViewModel>>> 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
@@ -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<ActionResult<RunViewModel>> GetRun(Guid id)
@@ -35,7 +35,7 @@ public async Task<ActionResult<RunViewModel>> 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<ActionResult> 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<ActionResult<CategoryViewModel>> GetCategoryForRun(Guid id)

diff --git 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<ActionResult<UserViewModel>> GetUserById(
@@ -45,7 +45,8 @@ public async Task<ActionResult<UserViewModel>> 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
@@ -49,9 +49,9 @@
     <PackageReference Include="OneOf" Version="3.0.271" />
     <PackageReference Include="OneOf.SourceGenerator" Version="3.0.271" />
     <PackageReference Include="ReHackt.Extensions.Options.Validation" Version="8.0.2" />
-    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
-    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.6.2" />
-    <PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="6.6.2" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.7.3" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.7.3" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="6.7.3" />
   </ItemGroup>
 
   <ItemGroup>

diff --git 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",