📝 docs: adding swagger documentation

Author: larismourullo

src/DevTranslate.Api/Controllers/HomeController.cs

@@ -8,6 +8,7 @@ namespace DevTranslate.Api.Controllers
 {
     [Route("")]
     [ApiController]
+    [ApiExplorerSettings(IgnoreApi = true)]
     public class HomeController : ControllerBase
     {
         public IActionResult GetHome()

src/DevTranslate.Api/Controllers/TranslationsController.cs

@@ -1,9 +1,11 @@
 using DevTranslate.Api.Context;
 using DevTranslate.Api.DTO;
 using Microsoft.AspNetCore.Mvc;
+using Swashbuckle.AspNetCore.Annotations;
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Net.Mime;
 using System.Threading.Tasks;
 
 namespace DevTranslate.Api.Controllers
@@ -20,7 +22,15 @@ public TranslationsController(DevTranslateContext context)
         }
 
         [HttpGet]
-        public IActionResult SearchTranslations(string query, int? page = 1, int? pageSize = 10)
+        [SwaggerResponse(200, "List of translations", typeof(SearchTranslationResponse))]
+        [SwaggerOperation(
+            Summary = "Get a list of translations",
+            Description = "Get a paginated list of translations, optionally filtering by title, author or translator",
+            OperationId = "SearchTranslations",
+            Tags = new[] { "Translations" }
+        )]
+        [Produces(MediaTypeNames.Application.Json)]
+        public IActionResult SearchTranslations([FromQuery] SearchTranslationRequest request)
         {
             var databaseQuery = _context.Translations.Select(t => new SearchTranslationResult()
             {
@@ -35,12 +45,12 @@ public IActionResult SearchTranslations(string query, int? page = 1, int? pageSi
                 Type = t.Type
             });
 
-            if (!String.IsNullOrWhiteSpace(query))
+            if (!String.IsNullOrWhiteSpace(request.Query))
             {
-                databaseQuery = databaseQuery.Where(t => t.Title.Contains(query) || t.Author.Contains(query) || t.Translator.Contains(query));
+                databaseQuery = databaseQuery.Where(t => t.Title.Contains(request.Query) || t.Author.Contains(request.Query) || t.Translator.Contains(request.Query));
             }
 
-            var pagination = new PaginationResponse(page ?? 0, pageSize ?? 0, databaseQuery.Count());
+            var pagination = new PaginationResponse(request.Page ?? 0, request.PageSize ?? 0, databaseQuery.Count());
 
             databaseQuery = databaseQuery.Skip(pagination.PageSize * (pagination.Page - 1))
                                          .Take(pagination.PageSize);

src/DevTranslate.Api/DTO/PaginationResponse.cs

@@ -1,4 +1,5 @@
-using System;
+using Swashbuckle.AspNetCore.Annotations;
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
@@ -28,8 +29,13 @@ public PaginationResponse(int page, int pageSize, int totalRecords)
             TotalPages = Convert.ToInt32(Math.Ceiling(totalRecords / (pageSize * 1.0m)));
         }
 
+        [SwaggerSchema("The number of the page of records to be returned. Defaults to 1.", ReadOnly = false)]
         public int Page { get; }
+
+        [SwaggerSchema("Number of items per page. Can not be higher than 10 which is also its default value.", ReadOnly = false)]
         public int PageSize { get; }
+
+        [SwaggerSchema("Total number of page of records available for the requested page size.", ReadOnly = false)]
         public int TotalPages { get; }
     }
 }

src/DevTranslate.Api/DTO/SearchTranslationRequest.cs

@@ -0,0 +1,26 @@
+using Swashbuckle.AspNetCore.Annotations;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace DevTranslate.Api.DTO
+{
+    public class SearchTranslationRequest
+    {
+        public SearchTranslationRequest()
+        {
+            Page = 1;
+            PageSize = 10;
+        }
+
+        [SwaggerParameter("Query text for searching translations by title, author or translator. Any translation with that contains the text in any of these fields will be returned.")]
+        public string Query { get; set; }
+
+        [SwaggerParameter("The number of the page of records to be returned. Defaults to 1.")]
+        public int? Page { get; set; }
+
+        [SwaggerParameter("Number of items per page. Can not be higher than 10 which is also its default value.")]
+        public int? PageSize { get; set; }
+    }
+}

src/DevTranslate.Api/DTO/SearchTranslationResponse.cs

@@ -1,4 +1,5 @@
-using System;
+using Swashbuckle.AspNetCore.Annotations;
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
@@ -13,6 +14,7 @@ public SearchTranslationResponse(IQueryable<SearchTranslationResult> translation
             Pagination = pagination;
         }
 
+        [SwaggerSchema(Nullable = false)]
         public List<SearchTranslationResult> Translations { get; set; }
     }
 }

src/DevTranslate.Api/DTO/SearchTranslationResult.cs

@@ -1,4 +1,5 @@
 using DevTranslate.Api.Entities;
+using Swashbuckle.AspNetCore.Annotations;
 using System;
 using System.Collections.Generic;
 using System.Linq;
@@ -8,14 +9,31 @@ namespace DevTranslate.Api.DTO
 {
     public class SearchTranslationResult
     {
+        [SwaggerSchema(Nullable = false)]
         public int Id { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public string Title { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public string Author { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public string Translator { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public Language Language { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public string Url { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public string ImageUrl { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public TranslationStatus Status { get; set; }
+
+        [SwaggerSchema(Nullable = false)]
         public TranslationType Type { get; set; }
     }
 }

src/DevTranslate.Api/DevTranslate.Api.csproj

@@ -16,6 +16,8 @@
     </PackageReference>
     <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="3.2.2" />
     <PackageReference Include="Pomelo.EntityFrameworkCore.MySql.Design" Version="1.1.2" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.0.5" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.0.5" />
   </ItemGroup>
 
 </Project>

src/DevTranslate.Api/Startup.cs

@@ -9,6 +9,7 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
+using Microsoft.OpenApi.Models;
 using Pomelo.EntityFrameworkCore.MySql.Infrastructure;
 
 namespace DevTranslate.Api
@@ -47,17 +48,15 @@ public void ConfigureServices(IServiceCollection services)
             {
                 options.UseMySql(Configuration.GetConnectionString("DevTranslateConnectionString"), mySqlOptions =>
                     {
-                        if (Environment.IsDevelopment())
-                        {
-                            mySqlOptions.ServerVersion(new Version(5, 7), ServerType.MySql);
-                        }
-
-                        if (Environment.IsProduction())
-                        {
-                            mySqlOptions.ServerVersion(new Version(8, 0), ServerType.MySql);
-                        }
+                        mySqlOptions.ServerVersion(new Version(8, 0), ServerType.MySql);
                     });
             });
+
+            services.AddSwaggerGen(c => 
+            { 
+                c.SwaggerDoc("v2", new OpenApiInfo { Title = "Devtranslate API", Version = "v2" });
+                c.EnableAnnotations();
+            });
         }
 
         public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
@@ -79,6 +78,16 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
 
             app.UseCors();
 
+            app.UseSwagger();
+
+            if (env.IsDevelopment())
+            {
+                app.UseSwaggerUI(c =>
+                {
+                    c.SwaggerEndpoint("/swagger/v2/swagger.json", "Devtranslate API V2");
+                });
+            }
+
             app.UseEndpoints(endpoints =>
             {
                 endpoints.MapControllers();