Skip to content

Commit c84cd03

Browse files
committed
📝 docs: adding swagger documentation
1 parent ca4926c commit c84cd03

File tree

8 files changed

+89
-15
lines changed

8 files changed

+89
-15
lines changed

src/DevTranslate.Api/Controllers/HomeController.cs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ namespace DevTranslate.Api.Controllers
88
{
99
[Route("")]
1010
[ApiController]
11+
[ApiExplorerSettings(IgnoreApi = true)]
1112
public class HomeController : ControllerBase
1213
{
1314
public IActionResult GetHome()

src/DevTranslate.Api/Controllers/TranslationsController.cs

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
using DevTranslate.Api.Context;
22
using DevTranslate.Api.DTO;
33
using Microsoft.AspNetCore.Mvc;
4+
using Swashbuckle.AspNetCore.Annotations;
45
using System;
56
using System.Collections.Generic;
67
using System.Linq;
8+
using System.Net.Mime;
79
using System.Threading.Tasks;
810

911
namespace DevTranslate.Api.Controllers
@@ -20,7 +22,15 @@ public TranslationsController(DevTranslateContext context)
2022
}
2123

2224
[HttpGet]
23-
public IActionResult SearchTranslations(string query, int? page = 1, int? pageSize = 10)
25+
[SwaggerResponse(200, "List of translations", typeof(SearchTranslationResponse))]
26+
[SwaggerOperation(
27+
Summary = "Get a list of translations",
28+
Description = "Get a paginated list of translations, optionally filtering by title, author or translator",
29+
OperationId = "SearchTranslations",
30+
Tags = new[] { "Translations" }
31+
)]
32+
[Produces(MediaTypeNames.Application.Json)]
33+
public IActionResult SearchTranslations([FromQuery] SearchTranslationRequest request)
2434
{
2535
var databaseQuery = _context.Translations.Select(t => new SearchTranslationResult()
2636
{
@@ -35,12 +45,12 @@ public IActionResult SearchTranslations(string query, int? page = 1, int? pageSi
3545
Type = t.Type
3646
});
3747

38-
if (!String.IsNullOrWhiteSpace(query))
48+
if (!String.IsNullOrWhiteSpace(request.Query))
3949
{
40-
databaseQuery = databaseQuery.Where(t => t.Title.Contains(query) || t.Author.Contains(query) || t.Translator.Contains(query));
50+
databaseQuery = databaseQuery.Where(t => t.Title.Contains(request.Query) || t.Author.Contains(request.Query) || t.Translator.Contains(request.Query));
4151
}
4252

43-
var pagination = new PaginationResponse(page ?? 0, pageSize ?? 0, databaseQuery.Count());
53+
var pagination = new PaginationResponse(request.Page ?? 0, request.PageSize ?? 0, databaseQuery.Count());
4454

4555
databaseQuery = databaseQuery.Skip(pagination.PageSize * (pagination.Page - 1))
4656
.Take(pagination.PageSize);

src/DevTranslate.Api/DTO/PaginationResponse.cs

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
using System;
1+
using Swashbuckle.AspNetCore.Annotations;
2+
using System;
23
using System.Collections.Generic;
34
using System.Linq;
45
using System.Threading.Tasks;
@@ -28,8 +29,13 @@ public PaginationResponse(int page, int pageSize, int totalRecords)
2829
TotalPages = Convert.ToInt32(Math.Ceiling(totalRecords / (pageSize * 1.0m)));
2930
}
3031

32+
[SwaggerSchema("The number of the page of records to be returned. Defaults to 1.", ReadOnly = false)]
3133
public int Page { get; }
34+
35+
[SwaggerSchema("Number of items per page. Can not be higher than 10 which is also its default value.", ReadOnly = false)]
3236
public int PageSize { get; }
37+
38+
[SwaggerSchema("Total number of page of records available for the requested page size.", ReadOnly = false)]
3339
public int TotalPages { get; }
3440
}
3541
}
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
using Swashbuckle.AspNetCore.Annotations;
2+
using System;
3+
using System.Collections.Generic;
4+
using System.Linq;
5+
using System.Threading.Tasks;
6+
7+
namespace DevTranslate.Api.DTO
8+
{
9+
public class SearchTranslationRequest
10+
{
11+
public SearchTranslationRequest()
12+
{
13+
Page = 1;
14+
PageSize = 10;
15+
}
16+
17+
[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.")]
18+
public string Query { get; set; }
19+
20+
[SwaggerParameter("The number of the page of records to be returned. Defaults to 1.")]
21+
public int? Page { get; set; }
22+
23+
[SwaggerParameter("Number of items per page. Can not be higher than 10 which is also its default value.")]
24+
public int? PageSize { get; set; }
25+
}
26+
}

src/DevTranslate.Api/DTO/SearchTranslationResponse.cs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
using System;
1+
using Swashbuckle.AspNetCore.Annotations;
2+
using System;
23
using System.Collections.Generic;
34
using System.Linq;
45
using System.Threading.Tasks;
@@ -13,6 +14,7 @@ public SearchTranslationResponse(IQueryable<SearchTranslationResult> translation
1314
Pagination = pagination;
1415
}
1516

17+
[SwaggerSchema(Nullable = false)]
1618
public List<SearchTranslationResult> Translations { get; set; }
1719
}
1820
}

src/DevTranslate.Api/DTO/SearchTranslationResult.cs

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
using DevTranslate.Api.Entities;
2+
using Swashbuckle.AspNetCore.Annotations;
23
using System;
34
using System.Collections.Generic;
45
using System.Linq;
@@ -8,14 +9,31 @@ namespace DevTranslate.Api.DTO
89
{
910
public class SearchTranslationResult
1011
{
12+
[SwaggerSchema(Nullable = false)]
1113
public int Id { get; set; }
14+
15+
[SwaggerSchema(Nullable = false)]
1216
public string Title { get; set; }
17+
18+
[SwaggerSchema(Nullable = false)]
1319
public string Author { get; set; }
20+
21+
[SwaggerSchema(Nullable = false)]
1422
public string Translator { get; set; }
23+
24+
[SwaggerSchema(Nullable = false)]
1525
public Language Language { get; set; }
26+
27+
[SwaggerSchema(Nullable = false)]
1628
public string Url { get; set; }
29+
30+
[SwaggerSchema(Nullable = false)]
1731
public string ImageUrl { get; set; }
32+
33+
[SwaggerSchema(Nullable = false)]
1834
public TranslationStatus Status { get; set; }
35+
36+
[SwaggerSchema(Nullable = false)]
1937
public TranslationType Type { get; set; }
2038
}
2139
}

src/DevTranslate.Api/DevTranslate.Api.csproj

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
</PackageReference>
1717
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="3.2.2" />
1818
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql.Design" Version="1.1.2" />
19+
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.0.5" />
20+
<PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.0.5" />
1921
</ItemGroup>
2022

2123
</Project>

src/DevTranslate.Api/Startup.cs

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
using Microsoft.Extensions.Configuration;
1010
using Microsoft.Extensions.DependencyInjection;
1111
using Microsoft.Extensions.Hosting;
12+
using Microsoft.OpenApi.Models;
1213
using Pomelo.EntityFrameworkCore.MySql.Infrastructure;
1314

1415
namespace DevTranslate.Api
@@ -47,17 +48,15 @@ public void ConfigureServices(IServiceCollection services)
4748
{
4849
options.UseMySql(Configuration.GetConnectionString("DevTranslateConnectionString"), mySqlOptions =>
4950
{
50-
if (Environment.IsDevelopment())
51-
{
52-
mySqlOptions.ServerVersion(new Version(5, 7), ServerType.MySql);
53-
}
54-
55-
if (Environment.IsProduction())
56-
{
57-
mySqlOptions.ServerVersion(new Version(8, 0), ServerType.MySql);
58-
}
51+
mySqlOptions.ServerVersion(new Version(8, 0), ServerType.MySql);
5952
});
6053
});
54+
55+
services.AddSwaggerGen(c =>
56+
{
57+
c.SwaggerDoc("v2", new OpenApiInfo { Title = "Devtranslate API", Version = "v2" });
58+
c.EnableAnnotations();
59+
});
6160
}
6261

6362
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
@@ -79,6 +78,16 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
7978

8079
app.UseCors();
8180

81+
app.UseSwagger();
82+
83+
if (env.IsDevelopment())
84+
{
85+
app.UseSwaggerUI(c =>
86+
{
87+
c.SwaggerEndpoint("/swagger/v2/swagger.json", "Devtranslate API V2");
88+
});
89+
}
90+
8291
app.UseEndpoints(endpoints =>
8392
{
8493
endpoints.MapControllers();

0 commit comments

Comments
 (0)