A Swashbuckle és a ASP.NET Core használatának első lépései

Jegyzet

A Swashbuckle nem érhető el a .NET 9-ben vagy újabb verzióiban. Alternatívaként tekintse meg a Az OpenAPI-támogatás áttekintése az ASP.NET Core API-alkalmazásokbanszakaszt.

A Swashbuckle három fő összetevőből áll:

• Swashbuckle.AspNetCore.Swagger: Swagger objektummodell és köztes szoftver, amely JSON-végpontként teszi elérhetővé SwaggerDocument objektumokat.

• Swashbuckle.AspNetCore.SwaggerGen: egy Swagger-generátor, amely közvetlenül az útvonalakból, vezérlőkből és modellekből készít SwaggerDocument objektumokat. Általában a Swagger végpont köztes szoftverrel kombinálva automatikusan elérhetővé teszi a Swagger JSON-t.

• Swashbuckle.AspNetCore.SwaggerUI: a Swagger felhasználói felületi eszköz beágyazott verziója. A Swagger JSON-t úgy értelmezi, hogy gazdag, testre szabható felületet hozzon létre a webes API funkcióinak leírásához. Beépített tesztkereteket tartalmaz a nyilvános módszerekhez.

Csomag telepítése

A Swashbuckle a következő módokon adható hozzá:

Visual Studio

• A Package Manager konzol ablakából:

  • Tekintse meg Nézet>Egyéb ablakok>Csomagkezelő konzol

  • Lépjen arra a könyvtárra, amelyben a .csproj fájl létezik

  • Hajtsa végre a következő parancsot:

    Install-Package Swashbuckle.AspNetCore -Version 6.6.2
    

• A NuGet-csomagok kezelése ablakban:

  • Kattintson a jobb gombbal a projektre Megoldáskezelőben>NuGet-csomagok kezelése
  • A csomag forrásának beállítása "nuget.org" értékre
  • Győződjön meg arról, hogy az "Előzetes kiadás befoglalása" lehetőség be van kapcsolva.
  • Írja be a "Swashbuckle.AspNetCore" kifejezést a keresőmezőbe
  • Válassza ki a legújabb "Swashbuckle.AspNetCore" csomagot a Tallózás lapon, majd kattintson a Telepítés gombra.

Visual Studio Code

Futtassa a következő parancsot az integrált terminálból:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

.NET CLI

Futtassa a következő parancsot:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

Swagger köztes szoftver hozzáadása és konfigurálása

Adja hozzá a Swagger-generátort a Program.csszolgáltatásgyűjteményéhez:

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Az előző példában látható AddEndpointsApiExplorer hívás csak minimális API-khozszükséges. További információért lásd ezt a StackOverflow bejegyzést .

Engedélyezze a köztes szoftvert a létrehozott JSON-dokumentum és a Swagger felhasználói felület kiszolgálásához, szintén a Program.cs:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Az előző kód csak akkor adja hozzá a Swagger köztes réteget, ha az aktuális környezet fejlesztési környezetre van beállítva. A UseSwaggerUI metódushívás lehetővé teszi a Swagger felhasználói felületi eszköz beágyazott verzióját.

Indítsa el az alkalmazást, és lépjen a https://localhost:<port>/swagger/v1/swagger.json. A végpontokat leíró létrehozott dokumentum a OpenAPI-specifikációban (openapi.json)látható módon jelenik meg.

A Swagger felhasználói felület megtalálható a https://localhost:<port>/swaggerhelyen. Fedezze fel az API-t a Swagger felhasználói felületén keresztül, és építse be más programokba.

Tipp

A Swagger felhasználói felületének az alkalmazás gyökerénél (https://localhost:<port>/) való kiszolgálásához állítsa a RoutePrefix tulajdonságot üres sztringre:

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

Ha címtárakat használ IIS-vel vagy fordított proxyval, állítsa a Swagger-végpontot egy relatív elérési útra a ./ előtag használatával. Például ./swagger/v1/swagger.json. A /swagger/v1/swagger.json használatakor az alkalmazás utasítást kap, hogy keresse meg a JSON-fájlt az URL valódi gyökerénél, valamint az útvonalelőtaggal, ha használják. Használjon például https://localhost:<port>/<route_prefix>/swagger/v1/swagger.jsonhttps://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.jsonhelyett.

Jegyzet

Alapértelmezés szerint a Swashbuckle létrehozza és elérhetővé teszi a Swagger JSON-t a specifikáció 3.0-s verziójában – hivatalos nevén OpenAPI-specifikációban. A visszamenőleges kompatibilitás támogatásához inkább a JSON 2.0-s formátumban való megjelenítését választhatja. Ez a 2.0 formátum olyan integrációk esetében fontos, mint a Microsoft Power Apps és a Microsoft Flow, amelyek jelenleg támogatják az OpenAPI 2.0-s verzióját. A 2.0 formátumra való választáshoz állítsa be a SerializeAsV2 tulajdonságot a Program.cs-ben.

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Testreszabás és bővítés

A Swagger lehetővé teszi az objektummodell dokumentálását és a felhasználói felület testreszabását a témának megfelelően.

API-információk és leírás

A AddSwaggerGen metódusnak átadott konfigurációs művelet olyan információkat ad hozzá, mint a szerző, a licenc és a leírás.

A Program.csimportálja a következő névteret a OpenApiInfo osztály használatához:

using Microsoft.OpenApi.Models;

A OpenApiInfo osztály használatával módosítsa a felhasználói felületen megjelenő információkat:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

A Swagger felhasználói felülete megjeleníti a verzió adatait:

XML-megjegyzések

Az XML-megjegyzések a következő módszerekkel engedélyezhetők:

Visual Studio

• Kattintson a jobb gombbal a projektre Megoldáskezelő, és válassza a Edit <project_name>.csprojlehetőséget.
• GenerateDocumentationFile hozzáadása a .csproj fájlhoz:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

GenerateDocumentationFile hozzáadása a .csproj fájlhoz:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

.NET CLI

GenerateDocumentationFile hozzáadása a .csproj fájlhoz:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Az XML-megjegyzések engedélyezése hibakeresési információkat biztosít a nem dokumentált nyilvános típusok és tagok számára. A nem dokumentált típusokat és tagokat a figyelmeztető üzenet jelzi. Az alábbi üzenet például az 1591-ben megjelenő figyelmeztető kód megsértését jelzi:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

A projektszintű figyelmeztetések mellőzéséhez definiálja a projektfájlban figyelmen kívül hagyandó figyelmeztető kódok pontosvesszővel tagolt listáját. Ha hozzáfűzi a figyelmeztetési kódokat a $(NoWarn);-hoz, akkor a C# alapértelmezett értékei is alkalmazásra kerülnek-ben.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Ha csak bizonyos tagok figyelmeztetéseit szeretné letiltani, a kódot #pragma figyelmeztetési előfeldolgozási irányelvekbe kell belefoglalnia. Ez a módszer olyan kódok esetében hasznos, amelyeket nem szabad az API-dokumentumokon keresztül elérhetővé tenni. Az alábbi példában a CS1591 figyelmeztető kód figyelmen kívül lesz hagyva a teljes TodoContext osztályban. A figyelmeztető kód érvényesítése az osztálydefiníció végén lesz visszaállítva. Adjon meg több figyelmeztető kódot vesszővel tagolt listával.

namespace SwashbuckleSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Konfigurálja a Swaggert az előző utasítások alapján létrehozott XML-fájl használatára. Linux vagy más nem Windows operációs rendszerek esetén a fájlnevek és az elérési utak megkülönböztethetik a kis- és nagybetűket. Egy TodoApi.XML fájl például Windows rendszeren érvényes, de nem Ubuntu.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Az előző kódban a Reflection a webes API-projektnek megfelelő XML-fájlnév létrehozására szolgál. Az AppContext.BaseDirectory tulajdonság az XML-fájl elérési útjának létrehozásához használható. Egyes Swagger-funkciók (például a bemeneti paraméterek sémája vagy a megfelelő attribútumokból származó HTTP-metódusok és válaszkódok) XML-dokumentációs fájl használata nélkül működnek. A legtöbb funkció, nevezetesen a metódusösszegzők, valamint a paraméterek és a válaszkódok leírása esetén az XML-fájl használata kötelező.

Három perjellel ellátott megjegyzések hozzáadása egy művelethez javítja a Swagger UI-t, mivel hozzáadja a leírást a szakaszfejléchez. Adjon hozzá egy <összefoglaló> elemet a Delete művelet fölé:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

A Swagger felhasználói felülete megjeleníti az előző kód <summary> elemének belső szövegét:

A felhasználói felületet a létrehozott JSON-séma vezérli:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Adjon hozzá egy <megjegyzés> elemet a Create műveletmetódus dokumentációjában. Kiegészíti a <summary> elemben megadott információkat, és robusztusabb Swagger felhasználói felületet biztosít. A <remarks> elem tartalma szövegből, JSON-ból vagy XML-ből állhat.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Figyelje meg a felhasználói felület fejlesztéseit az alábbi megjegyzésekkel:

Adatjegyzetek

Jelölje meg a modellt a System.ComponentModel.DataAnnotations névtérben található attribútumokkal, hogy segítsen a Swagger felhasználói felület összetevőinek meghajtásában.

Adja hozzá a [Required] attribútumot a Name osztály TodoItem tulajdonságához:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace SwashbuckleSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Az attribútum jelenléte megváltoztatja a felhasználói felület viselkedését, és módosítja a mögöttes JSON-sémát:

"schemas": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "format": "int64"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "type": "boolean",
                "default": false
            }
        },
        "additionalProperties": false
    }
},

Adja hozzá a [Produces("application/json")] attribútumot az API-vezérlőhöz. Célja, hogy deklarálja, hogy a vezérlő műveletei támogatják alkalmazás/jsonválasztartalmat:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

A médiatípus legördülő menü ezt a tartalomtípust választja alapértelmezettként a vezérlő GET műveleteihez:

A webes API-ban az adatjegyzetek használatának növekedésével a felhasználói felület és az API súgóoldalai leíróbbá és hasznosabbá válnak.

Választípusok leírása

A webes API-t használó fejlesztők leginkább a visszaadott adatokkal foglalkoznak, különösen a választípusokkal és a hibakódokkal (ha nem standard). A választípusok és hibakódok az XML-megjegyzésekben és az adatjegyzetekben jelennek meg.

A Create művelet sikeres végrehajtás esetén egy HTTP 201 állapotkódot ad vissza. A rendszer egy HTTP 400-állapotkódot ad vissza, amikor a közzétett kérelemtörzs null értékű. A Swagger felhasználói felületén található megfelelő dokumentáció nélkül a fogyasztó nem ismeri ezeket a várt eredményeket. A probléma megoldásához adja hozzá a kiemelt sorokat az alábbi példában:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

A Swagger felhasználói felülete most már egyértelműen dokumentálja a várt HTTP-válaszkódokat:

A konvenciók alternatívaként használhatók az egyes műveletek [ProducesResponseType]-nal történő explicit megjelölése helyett. További információ: Webes API-konvenciók használata.

A [ProducesResponseType] dekoráció támogatásához a Swashbuckle.AspNetCore.Annotations csomag bővítményeket kínál a válasz, séma és paraméter metaadatainak engedélyezéséhez és bővítéséhez.

A felhasználói felület testreszabása

Az alapértelmezett felhasználói felület funkcionális és megjeleníthető is. Az API dokumentációs oldalainak azonban az Ön márkáját vagy témáját kell képviselnie. A Swashbuckle-összetevők védjegyezéséhez hozzá kell adni az erőforrásokat a statikus fájlok kiszolgálásához, és létre kell építeni a mappastruktúrát a fájlok üzemeltetéséhez.

Statikus fájl köztes szoftver engedélyezése:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

További CSS-stíluslapok beszúrásához vegye fel őket a projekt wwwroot mappájába, és adja meg a köztes szoftver beállításainak relatív elérési útját:

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

További erőforrások

• Mintakód megtekintése vagy letöltése (hogyan lehet letölteni)
• Az API fejlesztői élményének javítása A Swagger dokumentációjával