Stevan/criminalmindsapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added xml comments for existing api parts and pieces.

Browse Source
This commit is contained in:
StevanFreeborn
2022-06-21 17:17:32 -05:00
parent 19729f4cc7
commit 5e201182ba
9 changed files with 149 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/Controllers/v1/EpisodesController.cs
+24 -7
View File
@@ -17,11 +17,19 @@ namespace server.Controllers.v1
_episodeRepository = episodeRepository;
}
/// <summary>
/// Gets a collection of episodes.
/// </summary>
/// <param name="filter">Filter parameters passed from query string.</param>
/// <response code="200">Returns the collection of episodes requested.</response>
/// <response code="400">Not a valid request.</response>
/// <response code="500">Failed to get episodes.</response>
/// <returns>A collection of episodes.</returns>
[MapToApiVersion("1.0")]
[HttpGet]
[ProducesResponseType(typeof(List<Episode>), 200)]
[ProducesResponseType(typeof(ValidationProblemDetails), 400)]
[ProducesResponseType(typeof(ProblemDetails), 500)]
[ProducesResponseType(typeof(List<Episode>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<List<Episode>>> GetEpisodesAsync([FromQuery] EpisodeFilter? filter)
{
try
@@ -36,12 +44,21 @@ namespace server.Controllers.v1
}
}
/// <summary>
/// Gets an episode by its number in the series.
/// </summary>
/// <param name="number">The number of the episode in the series.</param>
/// <response code="200">Returns the episode requested.</response>
/// <response code="400">Not a valid request.</response>
/// <response code="404">Unable to find an episode with the provided number.</response>
/// <response code="500">Failed to get episode.</response>
/// <returns>The episode requested.</returns>
[MapToApiVersion("1.0")]
[HttpGet("{number:int}")]
[ProducesResponseType(typeof(Episode), 200)]
[ProducesResponseType(typeof(ValidationProblemDetails), 400)]
[ProducesResponseType(typeof(ProblemDetails), 404)]
[ProducesResponseType(typeof(ProblemDetails), 500)]
[ProducesResponseType(typeof(Episode), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<Episode>> GetEpisodeByNumberAsync(int number)
{
try
server/Controllers/v1/SeasonsController.cs
+6 -6
View File
@@ -19,8 +19,8 @@ namespace server.Controllers.v1
[MapToApiVersion("1.0")]
[HttpGet]
[ProducesResponseType(typeof(List<Season>), 200)]
[ProducesResponseType(typeof(ProblemDetails), 500)]
[ProducesResponseType(typeof(List<Season>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<List<Season>>> GetSeasonsAsync()
{
try
@@ -37,10 +37,10 @@ namespace server.Controllers.v1
[MapToApiVersion("1.0")]
[HttpGet("{number:int}")]
[ProducesResponseType(typeof(Season), 200)]
[ProducesResponseType(typeof(ValidationProblemDetails), 400)]
[ProducesResponseType(typeof(ProblemDetails), 404)]
[ProducesResponseType(typeof(ProblemDetails),500)]
[ProducesResponseType(typeof(Season), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
public async Task<ActionResult<Season>> GetSeasonByNumberAsync(int number)
{
try
server/Filters/ApiVersionOperationFilter.cs
+20
View File
@@ -0,0 +1,20 @@
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
namespace server.Filters
{
public class ApiVersionOperationFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var headerParameter = operation.Parameters.Where(p => p.Name == "x-api-version").SingleOrDefault();
if (headerParameter != null)
{
headerParameter.Description = "Header value that identifies target version of api.";
headerParameter.Schema.Default = new OpenApiString(context.DocumentName.ToLower().Replace("v", ""));
}
}
}
}
server/Models/Character.cs
+27
View File
@@ -5,31 +5,58 @@ namespace server.Models
{
public class Character
{
/// <summary>
/// Identifier for the character.
/// </summary>
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string? Id { get; set; }
/// <summary>
/// The character's first name.
/// </summary>
[BsonElement("firstName")]
public string? FirstName { get; set; }
/// <summary>
/// The character's last name.
/// </summary>
[BsonElement("lastName")]
public string? LastName { get; set; }
/// <summary>
/// The first name of the actor who potrayed the character.
/// </summary>
[BsonElement("actorFirstName")]
public string? ActorFirstName { get; set; }
/// <summary>
/// The last name of the actor who potrayed the character.
/// </summary>
[BsonElement("actorLastName")]
public string? ActorLastName { get; set; }
/// <summary>
/// The seasons in which the character appeared.
/// </summary>
[BsonElement("seasons")]
public int[]? Seasons { get; set; }
/// <summary>
/// The first episode where the character appeared.
/// </summary>
[BsonElement("firstEpisode")]
public string? FirstEpisode { get; set; }
/// <summary>
/// The last episode where the character appeared.
/// </summary>
[BsonElement("lastEpisode")]
public string? LastEpisode { get; set; }
/// <summary>
/// A link to an image of the character.
/// </summary>
[BsonElement("image")]
public string? Image { get; set; }
}
server/Models/Episode.cs
+30
View File
@@ -5,35 +5,65 @@ namespace server.Models
{
public class Episode
{
/// <summary>
/// Identifier for the episode.
/// </summary>
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string? Id { get; set; }
/// <summary>
/// Season number for the episode.
/// </summary>
[BsonElement("season")]
public int? Season { get; set; }
/// <summary>
/// The episde number relative to the entire series.
/// </summary>
[BsonElement("numberInSeries")]
public int? NumberInSeries { get; set; }
/// <summary>
/// The episode number relative to its season.
/// </summary>
[BsonElement("numberInSeason")]
public int? NumberInSeason { get; set; }
/// <summary>
/// The title of the episode.
/// </summary>
[BsonElement("title")]
public string? Title { get; set; }
/// <summary>
/// A brief summary of the episode.
/// </summary>
[BsonElement("summary")]
public string? Summary { get; set; }
/// <summary>
/// The director of the episode.
/// </summary>
[BsonElement("directedBy")]
public string? DirectedBy { get; set; }
/// <summary>
/// The writer of the episode.
/// </summary>
[BsonElement("writtenBy")]
public string[]? WrittenBy { get; set; }
/// <summary>
/// Date the episode aired.
/// </summary>
[BsonElement("airDate")]
[BsonDateTimeOptions(DateOnly = true)]
public DateTime? AirDate { get; set; }
/// <summary>
/// Number of us viewers in millions for the episode.
/// </summary>
[BsonElement("usViewersInMillions")]
public double? UsViewersInMillions { get; set; }
server/Models/Quote.cs
+18
View File
@@ -5,22 +5,40 @@ namespace server.Models
{
public class Quote
{
/// <summary>
/// Identifier for the quote.
/// </summary>
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string? Id { get; set; }
/// <summary>
/// The season number during which the quote was said.
/// </summary>
[BsonElement("season")]
public int? Season { get; set; }
/// <summary>
/// The episode number during which the quote was said.
/// </summary>
[BsonElement("episode")]
public int Episode { get; set; }
/// <summary>
/// The quote text.
/// </summary>
[BsonElement("text")]
public string? Text { get; set; }
/// <summary>
/// The source of the quote.
/// </summary>
[BsonElement("source")]
public string? Source { get; set; }
/// <summary>
/// The narrator of the quote.
/// </summary>
[BsonElement("narrator")]
public string? Narrator { get; set; }
}
server/Models/Season.cs
+15
View File
@@ -5,20 +5,35 @@ namespace server.Models
{
public class Season
{
/// <summary>
/// Identifier for the season.
/// </summary>
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string? Id { get; set; }
/// <summary>
/// The season number.
/// </summary>
[BsonElement("seasonNumber")]
public int? SeasonNumber { get; set; }
/// <summary>
/// The number of episodes in the season.
/// </summary>
[BsonElement("numberOfEpisodes")]
public int? NumberOfEpisodes { get; set; }
/// <summary>
/// The date the season first aired.
/// </summary>
[BsonElement("dateFirstAired")]
[BsonDateTimeOptions(DateOnly = true)]
public DateTime? DateFirstAired { get; set; }
/// <summary>
/// The date the season last aired.
/// </summary>
[BsonElement("dateLastAired")]
[BsonDateTimeOptions(DateOnly = true)]
public DateTime? DateLastAired { get; set; }
server/Options/ConfigureSwaggerOptions.cs
+7 -1
View File
@@ -30,7 +30,13 @@ namespace server.Options
{
Title = "criminalmindsapi",
Version = description.ApiVersion.ToString(),
Description = "An api that provides information about the Criminal Minds series."
Description = "An api that provides information about the Criminal Minds series.",
Contact = new OpenApiContact
{
Name = "Stevan Freeborn",
Email = "stevan.freeborn@gmail.com",
Url = new Uri("https://stevanfreeborn.com")
}
};
return info;
server/Program.cs
+2
View File
@@ -3,6 +3,7 @@ using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.Extensions.Options;
using Microsoft.OpenApi.Models;
using server.Filters;
using server.Options;
using server.Persistence;
using server.Persistence.Repositories;
@@ -48,6 +49,7 @@ builder.Services.AddSwaggerGen(options =>
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);
options.OperationFilter<ApiVersionOperationFilter>();
});
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();