Swashbuckle

Liens

• ASP.NET Core Web API help pages with Swagger / Open API
• Get started with NSwag and ASP.NET Core

Ajout de NSwag à un projet .Net Core

# pour vscode dotnet add MyProject.csproj package NSwag.AspNetCore # Ajoute au fichier MyProject.csproj: # <ItemGroup> # <PackageReference Include="NSwag.AspNetCore" Version="11.17.15" />

Url : http://localhost:<port>/swagger

Configuration

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

afficherStartup.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()

Test

• http://localhost:<port>/swagger
• http://localhost:<port>/swagger/v1/swagger.json

Ouvrir le navigateur sur swagger

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.