Liens
Installation
|
# pour vscode
dotnet add package NSwag.AspNetCore
# Add to the project file *.csproj:
# <ItemGroup>
# <PackageReference Include="NSwag.AspNetCore" Version="11.17.15" />
|
Configuration Web API
| Startup.cs
|
public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerDocument();
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseOpenApi();
app.UseSwaggerUi3();
|
Configuration MVC
| Startup.cs
|
using NJsonSchema;
using NSwag.AspNetCore;
using System.Reflection;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseMvc();
// à ajouter avant app.UseSpa
app.UseSwaggerUi(typeof(Startup).GetTypeInfo().Assembly, settings =>
{
settings.GeneratorSettings.DefaultPropertyNameHandling = PropertyNameHandling.CamelCase;
settings.PostProcess = document =>
{
//document.Info.Version = "v1";
document.Info.Title = "Test API";
document.Info.Description = "A simple ASP.NET Core web API";
//document.Info.TermsOfService = "None";
document.Info.Contact = new NSwag.SwaggerContact
{
Name = "Nicolas",
//Email = string.Empty,
//Url = "https://twitter.com/spboyer"
};
/*document.Info.License = new NSwag.SwaggerLicense
{
Name = "Use under LICX",
Url = "https://example.com/license"
};*/
};
});
|
Problème avec IActionResult
NSwag utilise la réflexion pour obtenir le type de retour. Avec IActionResult il ne peut pas.
|
[HttpGet]
// utiliser SwaggerResponse
[SwaggerResponse(HttpStatusCode.OK, typeof(IReadOnlyList<ItemDto>))]
[SwaggerResponse(HttpStatusCode.BadRequest, typeof(void))]
// ou ProducesResponseType
[ProducesResponseType(typeof(IReadOnlyList<ItemDto>), StatusCodes.Status200OK)]
public IActionResult Get()
|
Installation
|
dotnet add package Swashbuckle.AspNetCore
|
| Startup.cs
|
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "EFWebApi", Version = "v1" });
});
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "EFWebApi v1");
c.RoutePrefix = string.Empty; // serve the Swagger UI at the app's root (http://localhost:<port>/)
});
}
|
Usage
| Controllers/ItemController.cs
|
[ApiController]
[Produces("application/json")] // set the Media type
[Route("[controller]")]
public class ItemController : ControllerBase
{
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<Item>), StatusCodes.Status200OK)] // set the status code and the return type
public IActionResult Get() { /* ... */ }
}
|
XML documentation
| MyProject.csproj
|
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>1701;1702;1705;1591</NoWarn>
</PropertyGroup>
|
| Controllers/ItemController.cs
|
/// <summary>
/// Get the items.
/// </summary>
/// <remarks>
/// Sample request:
///
/// GET /item
///
/// </remarks>
/// <returns>The items</returns>
/// <response code="200">Returns the items</response>
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<Item>), StatusCodes.Status200OK)]
public IActionResult Get() { /* ... */ }
|
Url
| Url
|
Resource
|
| http://localhost:<port>/swagger |
swagger UI
|
| http://localhost:<port>/swagger/v1/swagger.json |
swagger json
|
Dans un projet Web API avec Visual Studio Code, ouvrir le navigateur sur la page swagger.
| .vscode\launch.json
|
{
"configurations": [
{
"serverReadyAction": {
"action": "openExternally",
"pattern": "^\\s*Now listening on:\\s+(https?://\\S+)",
"uriFormat": "%s/swagger"
},
// autre solution
"launchBrowser": {
"enabled": true,
"args": "${auto-detect-url}",
"windows": {
"command": "cmd.exe",
"args": "/C start ${auto-detect-url}/swagger/index.html?url=/swagger/v1/swagger.json#!/Items"
}
}
|
Paramètres optionnels
Swagger ne gère pas les paramètres optionnels s'ils font partie du chemin, il les considère comme des paramètres required.
