Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Endpoint Operation IDs #243

Merged
merged 2 commits into from
Sep 3, 2024
Merged

Add Endpoint Operation IDs #243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c31528a
Add endpoint operation IDs.
TheTedder Sep 2, 2024
fbf246d
Update swagger packages.
TheTedder Sep 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions LeaderboardBackend/Controllers/AccountController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.",
Expand Down Expand Up @@ -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.")]
Expand Down Expand Up @@ -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(
Expand All @@ -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.")]
Expand All @@ -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)]
Expand All @@ -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.")]
Expand Down
4 changes: 2 additions & 2 deletions LeaderboardBackend/Controllers/CategoriesController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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))]
Expand Down
8 changes: 4 additions & 4 deletions LeaderboardBackend/Controllers/LeaderboardsController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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.")]
Expand Down
5 changes: 3 additions & 2 deletions LeaderboardBackend/Controllers/RunsController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)]
Expand Down Expand Up @@ -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)
Expand Down
5 changes: 3 additions & 2 deletions LeaderboardBackend/Controllers/UsersController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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.")]
Expand Down
6 changes: 3 additions & 3 deletions LeaderboardBackend/LeaderboardBackend.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
19 changes: 19 additions & 0 deletions LeaderboardBackend/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
"Account"
],
"summary": "Registers a new User.",
"operationId": "register",
"requestBody": {
"description": "The `RegisterRequest` instance from which to register the `User`.",
"content": {
Expand Down Expand Up @@ -75,6 +76,7 @@
"Account"
],
"summary": "Logs a User in.",
"operationId": "login",
"requestBody": {
"description": "The `LoginRequest` instance with which to perform the login.",
"content": {
Expand Down Expand Up @@ -138,6 +140,7 @@
"Account"
],
"summary": "Resends the account confirmation link.",
"operationId": "resendConfirmationEmail",
"responses": {
"400": {
"description": "Bad Request",
Expand Down Expand Up @@ -170,6 +173,7 @@
"Account"
],
"summary": "Sends an account recovery email.",
"operationId": "sendRecoveryEmail",
"requestBody": {
"description": "The account recovery request.",
"content": {
Expand Down Expand Up @@ -206,6 +210,7 @@
"Account"
],
"summary": "Confirms a user account.",
"operationId": "confirmAccount",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -250,6 +255,7 @@
"Account"
],
"summary": "Tests an account recovery token for validity.",
"operationId": "testRecoveryToken",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -289,6 +295,7 @@
"Account"
],
"summary": "Recover the user's account by resetting their password to a new value.",
"operationId": "changePassword",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -357,6 +364,7 @@
"Categories"
],
"summary": "Gets a Category by its ID.",
"operationId": "getCategory",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -404,6 +412,7 @@
"Categories"
],
"summary": "Creates a new Category. This request is restricted to Moderators.",
"operationId": "createCategory",
"requestBody": {
"content": {
"application/json": {
Expand Down Expand Up @@ -459,6 +468,7 @@
"Leaderboards"
],
"summary": "Gets a leaderboard by its ID.",
"operationId": "getLeaderboard",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -506,6 +516,7 @@
"Leaderboards"
],
"summary": "Gets a Leaderboard by its slug.",
"operationId": "getLeaderboardBySlug",
"parameters": [
{
"name": "slug",
Expand Down Expand Up @@ -552,6 +563,7 @@
"Leaderboards"
],
"summary": "Gets leaderboards by their IDs.",
"operationId": "getLeaderboards",
"parameters": [
{
"name": "ids",
Expand Down Expand Up @@ -601,6 +613,7 @@
"Leaderboards"
],
"summary": "Creates a new leaderboard. This request is restricted to Administrators.",
"operationId": "createLeaderboard",
"requestBody": {
"content": {
"application/json": {
Expand Down Expand Up @@ -659,6 +672,7 @@
"Runs"
],
"summary": "Gets a Run by its ID.",
"operationId": "getRun",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -716,6 +730,7 @@
"Runs"
],
"summary": "Creates a new Run.",
"operationId": "createRun",
"requestBody": {
"content": {
"application/json": {
Expand Down Expand Up @@ -766,6 +781,8 @@
"tags": [
"Runs"
],
"summary": "Gets the category a run belongs to.",
"operationId": "getRunCategory",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -813,6 +830,7 @@
"Users"
],
"summary": "Gets a User by their ID.",
"operationId": "getUser",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -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",
Expand Down