Skip to content

Commit 8f5f3f9

Browse files
kylerattikyleratti
committed
fix: show all status code responses in docs
Fix #26
1 parent ecec103 commit 8f5f3f9

3 files changed

Lines changed: 107 additions & 37 deletions

File tree

‎WebApi/Controllers/LinkController.cs‎

Lines changed: 104 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@
44
using DataClasses;
55
using FruityFoundation.Base.Extensions;
66
using Microsoft.AspNetCore.Mvc;
7+
using Newtonsoft.Json;
78
using SnooBrowser.Browsers;
89
using SnooBrowser.Things;
10+
using Swashbuckle.AspNetCore.Annotations;
911
using WebApi.Models;
1012
using WebApi.Util;
1113

@@ -39,29 +41,33 @@ SubmissionBrowser submissionBrowser
3941
/// </summary>
4042
[HttpPost]
4143
[Route("")]
42-
[ProducesResponseType((int)HttpStatusCode.Created)]
44+
[SwaggerResponse((int)HttpStatusCode.Created)]
45+
[SwaggerResponse((int)HttpStatusCode.BadRequest,
46+
description: "Bad Request. The request could not be processed due to invalid data on the request.",
47+
typeof(BadRequestError))]
48+
[SwaggerResponse((int)HttpStatusCode.Conflict,
49+
description: "Conflict. This user has already provided this combination of reddit post ID, URL, and link type.",
50+
typeof(LinkAlreadyExistsError))]
4351
public async Task<IActionResult> SubmitLink([FromBody] SubmitLinkRequest linkRequest)
4452
{
4553
var validUrl = GetValidUriOrFail(linkRequest.LinkUrl);
4654
var linkKind = GetLinkKindOrFail(linkRequest.LinkType!.Value);
4755

4856
if ((await _linkProvider.FindLink(UserId, linkRequest.RedditPostId, validUrl.OriginalString, linkKind)).HasValue)
49-
return new ConflictObjectResult(new
50-
{
51-
message = TranslatedStrings.LinkController.LinkAlreadyExists,
52-
redditPostId = linkRequest.RedditPostId,
53-
url = validUrl.OriginalString,
54-
linkType = linkRequest.LinkType
55-
});
57+
return new ConflictObjectResult(new LinkAlreadyExistsError(
58+
Message: TranslatedStrings.LinkController.LinkAlreadyExists,
59+
RedditPostId: linkRequest.RedditPostId,
60+
Url: validUrl.OriginalString,
61+
LinkType: linkRequest.LinkType
62+
));
5663

5764
var maybeSubmission = await _submissionBrowser.GetSubmission(LinkThing.CreateFromShortId(linkRequest.RedditPostId));
5865

5966
if (!maybeSubmission.Try(out var submission) || submission.IsArchived || submission.IsLocked)
60-
return new BadRequestObjectResult(new
61-
{
62-
message = TranslatedStrings.LinkController.RedditPostIdIsNotValid(linkRequest.RedditPostId),
63-
redditPostId = linkRequest.RedditPostId
64-
});
67+
return new BadRequestObjectResult(new BadRequestError(
68+
Message: TranslatedStrings.LinkController.RedditPostIdIsNotValid(linkRequest.RedditPostId),
69+
RedditPostId: linkRequest.RedditPostId
70+
));
6571

6672
await _linkProvider.CreateLink(new NewLink(
6773
redditPostId: linkRequest.RedditPostId,
@@ -79,51 +85,59 @@ await _linkProvider.CreateLink(new NewLink(
7985
/// </summary>
8086
[HttpDelete]
8187
[Route("")]
82-
[ProducesResponseType((int)HttpStatusCode.OK)]
88+
[SwaggerResponse((int)HttpStatusCode.OK,
89+
description: "OK. The link has been queued for deletion.",
90+
typeof(LinkDeleteQueuedSuccessfully))]
91+
[SwaggerResponse((int)HttpStatusCode.NotFound,
92+
description: "Not Found. This user does not have this combination of reddit post ID, URL, and link type.",
93+
typeof(LinkNotFoundError))]
8394
public async Task<IActionResult> DeleteLinkByLinkData([FromBody] DeleteLinkRequest linkRequest)
8495
{
8596
var validUrl = GetValidUriOrFail(linkRequest.LinkUrl);
8697
var linkKind = GetLinkKindOrFail(linkRequest.LinkType!.Value);
8798

8899
if (!(await _linkProvider.FindLink(UserId, linkRequest.RedditPostId, validUrl.OriginalString, linkKind)).Try(out var link))
89-
return new NotFoundObjectResult(new
90-
{
91-
message = TranslatedStrings.LinkController.LinkNotFound,
92-
redditPostId = linkRequest.RedditPostId,
93-
url = validUrl.OriginalString
94-
});
100+
return new NotFoundObjectResult(new LinkNotFoundError(
101+
Message: TranslatedStrings.LinkController.LinkNotFound,
102+
RedditPostId: linkRequest.RedditPostId,
103+
Url: validUrl.OriginalString
104+
));
95105

96106
await _linkProvider.DeleteLinkById(link.LinkId);
97107

98-
return new OkObjectResult(new
99-
{
100-
message = TranslatedStrings.LinkController.LinkDeleted,
101-
redditPostId = link.RedditPostId
102-
});
108+
return new OkObjectResult(new LinkDeleteQueuedSuccessfully(
109+
Message: TranslatedStrings.LinkController.LinkDeleted,
110+
RedditPostId: link.RedditPostId,
111+
Url: link.LinkUrl
112+
));
103113
}
104114

105115
/// <summary>
106116
/// Delete an existing link by using the provided link ID.
107117
/// </summary>
108118
[HttpDelete]
109119
[Route("{linkId:int}")]
110-
[ProducesResponseType((int)HttpStatusCode.OK)]
120+
[SwaggerResponse((int)HttpStatusCode.OK,
121+
description: "OK. The link has been queued for deletion.",
122+
typeof(LinkDeleteQueuedSuccessfully))]
123+
[SwaggerResponse((int)HttpStatusCode.NotFound,
124+
description: "Not Found. This user does not have this combination of reddit post ID, URL, and link type.",
125+
typeof(LinkIdNotFoundError))]
111126
public async Task<IActionResult> DeleteLinkById([FromRoute] int linkId)
112127
{
113128
if (!(await _linkProvider.FindLinkById(UserId, linkId)).Try(out var link))
114-
return new NotFoundObjectResult(new
115-
{
116-
message = TranslatedStrings.LinkController.LinkIdNotFound(linkId),
117-
linkId
118-
});
129+
return new NotFoundObjectResult(new LinkIdNotFoundError(
130+
Message: TranslatedStrings.LinkController.LinkIdNotFound(linkId),
131+
LinkId: linkId
132+
));
119133

120134
await _linkProvider.DeleteLinkById(link.LinkId);
121135

122-
return new OkObjectResult(new
123-
{
124-
message = TranslatedStrings.LinkController.LinkDeleted,
125-
redditPostId = link.RedditPostId
126-
});
136+
return new OkObjectResult(new LinkDeleteQueuedSuccessfully(
137+
Message: TranslatedStrings.LinkController.LinkDeleted,
138+
RedditPostId: link.RedditPostId,
139+
Url: link.LinkUrl
140+
));
127141
}
128142

129143
/// <summary>
@@ -155,12 +169,65 @@ private static Uri GetValidUriOrFail(string linkUrl)
155169
};
156170

157171
return uri;
158-
}
172+
}
159173

160174
private static LinkKind GetLinkKindOrFail(SerializableLinkType serializableLinkType) => serializableLinkType switch
161175
{
162176
SerializableLinkType.Mirror => LinkKind.Mirror,
163177
SerializableLinkType.Download => LinkKind.Download,
164178
_ => throw new ArgumentOutOfRangeException(nameof(serializableLinkType), serializableLinkType, "Unknown link type")
165179
};
180+
181+
/// <summary>
182+
/// The error message returned when the submitted request has invalid data that must be corrected before it can be processed.
183+
/// </summary>
184+
/// <param name="Message">The error message.</param>
185+
/// <param name="RedditPostId">The reddit post ID.</param>
186+
private record BadRequestError(
187+
[property:JsonProperty("message")] string Message,
188+
[property:JsonProperty("redditPostId")] string RedditPostId);
189+
190+
/// <summary>
191+
/// The data model returned when a link is successfully queued for deletion.
192+
/// </summary>
193+
/// <param name="Message">The message from the server.</param>
194+
/// <param name="RedditPostId">The reddit post ID.</param>
195+
/// <param name="Url">The link that will be deleted from the list of links on the post.</param>
196+
private record LinkDeleteQueuedSuccessfully(
197+
[property:JsonProperty("message")] string Message,
198+
[property:JsonProperty("redditPostId")] string RedditPostId,
199+
[property:JsonProperty("url")] string Url);
200+
201+
/// <summary>
202+
/// The data model returned when a link specific link on a reddit post is not found but the API consumer expected it to be.
203+
/// </summary>
204+
/// <param name="Message">The message from the server.</param>
205+
/// <param name="RedditPostId">The reddit post ID.</param>
206+
/// <param name="Url">The provided URL.</param>
207+
private record LinkNotFoundError(
208+
[property:JsonProperty("message")] string Message,
209+
[property:JsonProperty("redditPostId")] string RedditPostId,
210+
[property:JsonProperty("url")] string Url);
211+
212+
/// <summary>
213+
/// The data model returned when the API consumer provided a specific link ID to delete but that link ID did not exist.
214+
/// </summary>
215+
/// <param name="Message">The message from the server.</param>
216+
/// <param name="LinkId">The provided link ID.</param>
217+
private record LinkIdNotFoundError(
218+
[property:JsonProperty("message")] string Message,
219+
[property:JsonProperty("linkId")] int LinkId);
220+
221+
/// <summary>
222+
/// The error message returned when the provided link already exists for the specified reddit post ID.
223+
/// </summary>
224+
/// <param name="Message">The error message from the API.</param>
225+
/// <param name="RedditPostId">The reddit post ID.</param>
226+
/// <param name="Url">The URL that was submitted.</param>
227+
/// <param name="LinkType">The type of link that was submitted.</param>
228+
private record LinkAlreadyExistsError(
229+
[property: JsonProperty("message")] string Message,
230+
[property: JsonProperty("redditPostId")] string RedditPostId,
231+
[property: JsonProperty("url")] string Url,
232+
[property: JsonProperty("linkType")] SerializableLinkType? LinkType);
166233
}

‎WebApi/Program.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@
3737

3838
opts.OperationFilter<JsonExceptionResponseOperationFilter>();
3939
opts.OperationFilter<UnauthorizedResponseOperationFilter>();
40+
opts.EnableAnnotations();
41+
opts.UseInlineDefinitionsForEnums();
4042
});
4143

4244
var app = builder.Build();

‎WebApi/WebApi.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
<ItemGroup>
2020
<PackageReference Include="SnooBrowser.Extensions.DependencyInjection" Version="3.0.4" />
2121
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
22+
<PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.4.0" />
2223
<PackageReference Include="System.Runtime.Caching" Version="7.0.0" />
2324
</ItemGroup>
2425

0 commit comments

Comments
 (0)