Megosztás a következőn keresztül:

Egyszerű, adatvezérelt CRUD-mikroszolgáltatás létrehozása

Tipp.

Ez a tartalom egy részlet a .NET-alkalmazásokhoz készült .NET-alkalmazásokhoz készült eBook, .NET Microservices Architecture című eBookból, amely elérhető a .NET Docs-on vagy egy ingyenesen letölthető PDF-fájlként, amely offline módban is olvasható.

PDF letöltése

.NET mikroszolgáltatások architektúrája konténerizált .NET alkalmazásokhoz e-könyv borító miniatűr.

Ez a szakasz egy egyszerű mikroszolgáltatás létrehozását ismerteti, amely létrehozási, olvasási, frissítési és törlési (CRUD) műveleteket hajt végre egy adatforráson.

Egyszerű CRUD-mikroszolgáltatás tervezése

Tervezési szempontból ez a típusú tárolóalapú mikroszolgáltatás nagyon egyszerű. Lehet, hogy a megoldandó probléma egyszerű, vagy talán a megvalósítás csak a koncepció bizonyítéka.

Egy egyszerű CRUD mikroszolgáltatás belső tervezési mintáját bemutató ábra.

6-4. ábra. Belső kialakítás egyszerű CRUD mikroszolgáltatásokhoz

Ilyen egyszerű adatmeghajtó szolgáltatás például az eShopOnContainers mintaalkalmazás katalógus-mikroszolgáltatása. Ez a szolgáltatástípus egyetlen ASP.NET Core Web API-projektben valósítja meg az összes funkcióját, amely osztályokat tartalmaz az adatmodellhez, az üzleti logikához és az adatelérési kódhoz. A kapcsolódó adatokat egy SQL Serveren futó adatbázisban is tárolja (fejlesztési/tesztelési célokra egy másik tárolóként), de bármilyen rendszeres SQL Server-gazdagép is lehet, ahogyan az a 6–5. ábrán látható.

Adatvezérelt/CRUD mikroszolgáltatás-tárolót bemutató ábra.

6-5. ábra. Egyszerű adatvezérelt/CRUD mikroszolgáltatás-tervezés

Az előző ábrán a katalógus adatbázisát tartalmazó logikai katalógus-mikroszolgáltatás látható, amely ugyanabban a Docker-gazdagépben lehet vagy nem. Ha az adatbázis ugyanabban a Docker-gazdagépben van, az jó lehet a fejlesztéshez, de éles környezetben nem. Ilyen típusú szolgáltatás fejlesztésekor csak ASP.NET Core-ra és egy adatelérési API-ra vagy ORM-re van szüksége, például az Entity Framework Core-ra. A Swashbuckle használatával automatikusan létrehozhat Swagger-metaadatokat is, hogy a következő szakaszban leírtak szerint leírást adjon a szolgáltatás által kínált szolgáltatásokról.

Vegye figyelembe, hogy az adatbázis-kiszolgáló, például az SQL Server Docker-tárolón belüli futtatása kiválóan alkalmas fejlesztői környezetek számára, mivel az összes függősége üzembe helyezheti és futtatható anélkül, hogy adatbázist kellene kiépítenie a felhőben vagy a helyszínen. Ez a megközelítés az integrációs tesztek futtatásakor kényelmes. Éles környezetekben azonban nem ajánlott adatbázis-kiszolgálót futtatni egy tárolóban, mert ezzel a módszerrel általában nem érhető el magas rendelkezésre állás. Az Azure-beli éles környezetben ajánlott az Azure SQL DB vagy bármely más olyan adatbázis-technológia használata, amely magas rendelkezésre állást és magas méretezhetőséget biztosít. NoSQL-megközelítés esetén például a CosmosDB-t választhatja.

Végül a Dockerfile és docker-compose.yml metaadatfájlok szerkesztésével konfigurálhatja a tároló rendszerképének létrehozását – az alaprendszerképet, valamint a tervezési beállításokat, például a belső és külső neveket és a TCP-portokat.

Egyszerű CRUD-mikroszolgáltatás megvalósítása a ASP.NET Core használatával

Ha egy egyszerű CRUD mikroszolgáltatást szeretne implementálni a .NET és a Visual Studio használatával, először hozzon létre egy egyszerű ASP.NET Core Web API-projektet (amely .NET-en fut, hogy linuxos Docker-gazdagépen fusson), ahogyan a 6–6. ábrán látható.

Képernyőkép a Visual Studiosról, amelyen a projekt beállítása látható.

6-6. ábra. ASP.NET Core Web API-projekt létrehozása a Visual Studio 2019-ben

ASP.NET Core Web API-projekt létrehozásához először válasszon ki egy ASP.NET Core-webalkalmazást, majd válassza ki az API-típust. A projekt létrehozása után ugyanúgy implementálhatja az MVC-vezérlőket, mint bármely más webes API-projektben az Entity Framework API vagy más API használatával. Egy új Webes API-projektben láthatja, hogy a mikroszolgáltatásban az egyetlen függősége ASP.NET Core-on van. Belsőleg a Microsoft.AspNetCore.All függőségen belül az Entity Frameworkre és sok más .NET NuGet-csomagra hivatkozik, ahogyan az a 6–7. ábrán látható.

Képernyőkép a VS-ről, amelyen a Catalog.Api NuGet-függőségei láthatók.

6-7. ábra. Függőségek egy egyszerű CRUD Webes API-mikroszolgáltatásban

Az API-projekt Microsoft.AspNetCore.App NuGet-csomagra mutató hivatkozásokat tartalmaz, amelyek az összes alapvető csomagra mutató hivatkozásokat tartalmaznak. Más csomagokat is tartalmazhat.

CRUD Webes API-szolgáltatások implementálása az Entity Framework Core-nal

Az Entity Framework (EF) Core a népszerű Entity Framework adathozzáférési technológia egyszerűsített, bővíthető és platformfüggetlen verziója. Az EF Core egy objektum-relációs leképező (ORM), amely lehetővé teszi a .NET-fejlesztők számára, hogy .NET-objektumokat használó adatbázissal dolgozzanak.

A katalógus mikroszolgáltatása az EF-t és az SQL Server-szolgáltatót használja, mivel az adatbázisa egy tárolóban fut a LinuxHoz készült SQL Server Docker-lemezképpel. Az adatbázist azonban bármilyen SQL Serverre üzembe lehet helyezni, például a helyszíni Windows vagy az Azure SQL DB-ben. Az egyetlen dolog, amit módosítania kell, az a ASP.NET Webes API mikroszolgáltatás kapcsolati sztring.

Az adatmodell

Az EF Core használatával az adathozzáférés egy modell használatával történik. A modell (tartománymodell) entitásosztályokból és származtatott környezetekből (DbContext) áll, amelyek az adatbázissal való munkamenetet jelölik, lehetővé téve az adatok lekérdezését és mentését. Létrehozhat egy modellt egy meglévő adatbázisból, manuálisan kódálhat egy modellt az adatbázisnak megfelelően, vagy ef-migrálási technikával létrehozhat egy adatbázist a modellből az első kódelső megközelítéssel (ami megkönnyíti az adatbázis továbbfejlesztét, ahogy a modell idővel változik). A katalógus mikroszolgáltatásához az utolsó módszert használták. A CatalogItem entitásosztályra az alábbi kód példában látható egy példa, amely egy egyszerű egyszerű régi osztályobjektum (POCO) entitásosztály.

public class CatalogItem
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
    public string PictureFileName { get; set; }
    public string PictureUri { get; set; }
    public int CatalogTypeId { get; set; }
    public CatalogType CatalogType { get; set; }
    public int CatalogBrandId { get; set; }
    public CatalogBrand CatalogBrand { get; set; }
    public int AvailableStock { get; set; }
    public int RestockThreshold { get; set; }
    public int MaxStockThreshold { get; set; }

    public bool OnReorder { get; set; }
    public CatalogItem() { }

    // Additional code ...
}

Olyan DbContextre is szüksége van, amely az adatbázissal folytatott munkamenetet jelöli. A katalógus mikroszolgáltatása esetében a CatalogContext osztály a DbContext alaposztályból származik, ahogyan az a következő példában látható:

public class CatalogContext : DbContext
{
    public CatalogContext(DbContextOptions<CatalogContext> options) : base(options)
    { }
    public DbSet<CatalogItem> CatalogItems { get; set; }
    public DbSet<CatalogBrand> CatalogBrands { get; set; }
    public DbSet<CatalogType> CatalogTypes { get; set; }

    // Additional code ...
}

További DbContext implementációk is lehetnek. A Catalog.API mikroszolgáltatásban például van egy második DbContext név CatalogContextSeed , ahol automatikusan kitölti a mintaadatokat, amikor először próbál hozzáférni az adatbázishoz. Ez a módszer a demóadatok és az automatizált tesztelési forgatókönyvek esetében is hasznos.

A metódussal testre szabhatja az DbContextOnModelCreating objektum-/adatbázis-entitásleképezéseket és más EF bővíthetőségi pontokat.

Adatok lekérdezése webes API-vezérlőkből

Az entitásosztályok példányai általában a Language-Integrated Query (LINQ) használatával lesznek lekérve az adatbázisból, ahogyan az alábbi példában látható:

[Route("api/v1/[controller]")]
public class CatalogController : ControllerBase
{
    private readonly CatalogContext _catalogContext;
    private readonly CatalogSettings _settings;
    private readonly ICatalogIntegrationEventService _catalogIntegrationEventService;

    public CatalogController(
        CatalogContext context,
        IOptionsSnapshot<CatalogSettings> settings,
        ICatalogIntegrationEventService catalogIntegrationEventService)
    {
        _catalogContext = context ?? throw new ArgumentNullException(nameof(context));
        _catalogIntegrationEventService = catalogIntegrationEventService
            ?? throw new ArgumentNullException(nameof(catalogIntegrationEventService));

        _settings = settings.Value;
        context.ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
    }

    // GET api/v1/[controller]/items[?pageSize=3&pageIndex=10]
    [HttpGet]
    [Route("items")]
    [ProducesResponseType(typeof(PaginatedItemsViewModel<CatalogItem>), (int)HttpStatusCode.OK)]
    [ProducesResponseType(typeof(IEnumerable<CatalogItem>), (int)HttpStatusCode.OK)]
    [ProducesResponseType((int)HttpStatusCode.BadRequest)]
    public async Task<IActionResult> ItemsAsync(
        [FromQuery]int pageSize = 10,
        [FromQuery]int pageIndex = 0,
        string ids = null)
    {
        if (!string.IsNullOrEmpty(ids))
        {
            var items = await GetItemsByIdsAsync(ids);

            if (!items.Any())
            {
                return BadRequest("ids value invalid. Must be comma-separated list of numbers");
            }

            return Ok(items);
        }

        var totalItems = await _catalogContext.CatalogItems
            .LongCountAsync();

        var itemsOnPage = await _catalogContext.CatalogItems
            .OrderBy(c => c.Name)
            .Skip(pageSize * pageIndex)
            .Take(pageSize)
            .ToListAsync();

        itemsOnPage = ChangeUriPlaceholder(itemsOnPage);

        var model = new PaginatedItemsViewModel<CatalogItem>(
            pageIndex, pageSize, totalItems, itemsOnPage);

        return Ok(model);
    }
    //...
}
Adatok mentése

Az adatok létrehozása, törlése és módosítása az adatbázisban az entitásosztályok példányainak használatával történik. A webes API-vezérlőkhöz a következő, szigorúan kódolt példához hasonló kódot (ebben az esetben az adatok szimulálása) is hozzáadhat.

var catalogItem = new CatalogItem() {CatalogTypeId=2, CatalogBrandId=2,
                                     Name="Roslyn T-Shirt", Price = 12};
_context.Catalog.Add(catalogItem);
_context.SaveChanges();
Függőséginjektálás ASP.NET Core- és webes API-vezérlőkben

A ASP.NET Core-ban a függőséginjektálást (DI) a dobozon kívül is használhatja. Nem kell beállítania egy harmadik féltől származó Inversion of Control (IoC) tárolót, bár igény szerint csatlakoztathatja az előnyben részesített IoC-tárolót a ASP.NET Core-infrastruktúrához. Ebben az esetben ez azt jelenti, hogy közvetlenül injektálhatja a szükséges EF DBContextet vagy további adattárakat a vezérlőkonstruktoron keresztül.

CatalogController A korábban említett osztályban ( CatalogContext amely örökli DbContexta ) típust a konstruktor többi szükséges objektumával együtt injektáljukCatalogController().

A Web API-projektben fontos konfiguráció a DbContext osztály regisztrációja a szolgáltatás IoC-tárolójába. Ezt általában a metódus meghívásával teheti meg a builder.Services.AddDbContext<CatalogContext>() fájlban, ahogy az alábbi egyszerűsített példában is látható:

// Additional code...

builder.Services.AddDbContext<CatalogContext>(options =>
{
    options.UseSqlServer(builder.Configuration["ConnectionString"],
    sqlServerOptionsAction: sqlOptions =>
    {
        sqlOptions.MigrationsAssembly(
            typeof(Program).GetTypeInfo().Assembly.GetName().Name);

        //Configuring Connection Resiliency:
        sqlOptions.
            EnableRetryOnFailure(maxRetryCount: 5,
            maxRetryDelay: TimeSpan.FromSeconds(30),
            errorNumbersToAdd: null);
    });

    // Changing default behavior when client evaluation occurs to throw.
    // Default in EFCore would be to log warning when client evaluation is done.
    options.ConfigureWarnings(warnings => warnings.Throw(
        RelationalEventId.QueryClientEvaluationWarning));
});

Fontos

A Microsoft azt javasolja, hogy a legbiztonságosabb hitelesítési folyamatot használja. Ha azure SQL-hez csatlakozik, az Azure-erőforrások felügyelt identitásai az ajánlott hitelesítési módszer.

További erőforrások

A Docker-tárolók által használt adatbázis-kapcsolati sztring és környezeti változók

Használhatja a ASP.NET Core-beállításokat, és hozzáadhat egy ConnectionString tulajdonságot a settings.json fájlhoz az alábbi példában látható módon:

{
    "ConnectionString": "Server=tcp:127.0.0.1,5433;Initial Catalog=Microsoft.eShopOnContainers.Services.CatalogDb;User Id=sa;Password=[PLACEHOLDER]",
    "ExternalCatalogBaseUrl": "http://host.docker.internal:5101",
    "Logging": {
        "IncludeScopes": false,
        "LogLevel": {
            "Default": "Debug",
            "System": "Information",
            "Microsoft": "Information"
        }
    }
}

A settings.json fájl alapértelmezett értékekkel rendelkezhet a ConnectionString tulajdonsághoz vagy bármely más tulajdonsághoz. Ezeket a tulajdonságokat azonban felülírja a docker-compose.override.yml fájlban megadott környezeti változók értéke a Docker használatakor.

A docker-compose.yml vagy docker-compose.override.yml fájlokból inicializálhatja ezeket a környezeti változókat, hogy a Docker operációsrendszer-környezeti változóként állítsa be őket, ahogyan az a következő docker-compose.override.yml fájlban is látható (a példában szereplő kapcsolati sztring és egyéb sorok körbefutnak, de nem tördelik be a saját fájlba).

# docker-compose.override.yml

#
catalog-api:
  environment:
    - ConnectionString=Server=sqldata;Database=Microsoft.eShopOnContainers.Services.CatalogDb;User Id=sa;Password=[PLACEHOLDER]
    # Additional environment variables for this service
  ports:
    - "5101:80"

Fontos

A Microsoft azt javasolja, hogy a legbiztonságosabb hitelesítési folyamatot használja. Ha azure SQL-hez csatlakozik, az Azure-erőforrások felügyelt identitásai az ajánlott hitelesítési módszer.

A megoldás szintjén a docker-compose.yml fájlok nem csak rugalmasabbak, mint a projekt vagy a mikroszolgáltatás szintjén lévő konfigurációs fájlok, hanem biztonságosabbak is, ha felülbírálja a docker-compose fájlokban deklarált környezeti változókat az üzembehelyezési eszközök által beállított értékekkel, például az Azure DevOps Services Docker üzembe helyezési feladataival.

Végül ezt az értéket a kódból builder.Configuration["ConnectionString"]is lekérheti egy korábbi példakódban látható módon.

Éles környezetek esetén azonban érdemes lehet további módszereket is megvizsgálni a titkos kulcsok, például a kapcsolati sztring tárolására. Az alkalmazás titkos kulcsának kezelésére kiváló módszer az Azure Key Vault használata.

Az Azure Key Vault segít a felhőalkalmazások és -szolgáltatások által használt titkosítási kulcsok és titkos kódok tárolásában és védelmében. A titkos kód minden, amit szigorúan szabályozni szeretne, például API-kulcsokat, kapcsolati sztring, jelszavakat stb., és a szigorú vezérlés többek között magában foglalja a használat naplózását, a lejárat beállítását, a hozzáférés kezelését.

Az Azure Key Vault lehetővé teszi az alkalmazás titkos kulcsainak használatának részletes vezérlését anélkül, hogy bárkinek tudatnia kellene őket. A titkos kulcsok akár a fokozott biztonság érdekében is elforgathatók anélkül, hogy megzavarná a fejlesztést vagy a műveleteket.

Az alkalmazásokat regisztrálni kell a szervezet Active Directoryjában, hogy használni tudják a Key Vaultot.

További részletekért tekintse meg a Key Vault alapfogalmainak dokumentációját .

Verziószámozás megvalósítása ASP.NET webes API-kban

Az üzleti követelmények változásával új erőforrásgyűjtemények vehetők fel, az erőforrások közötti kapcsolatok megváltozhatnak, és az erőforrásokban lévő adatok struktúrája módosítható. A webes API frissítése az új követelmények kezelésére viszonylag egyszerű folyamat, de figyelembe kell vennie, hogy az ilyen módosítások milyen hatással lesznek a webes API-t használó ügyfélalkalmazásokra. Bár a webes API-t tervező és megvalósító fejlesztő teljes mértékben felügyeli ezt az API-t, a fejlesztő nem rendelkezik ugyanolyan szintű vezérléssel az ügyfélalkalmazások felett, amelyeket külső szervezetek hozhatnak létre távolról.

A verziószámozás lehetővé teszi a webes API-k számára, hogy jelezzék az általa kínált funkciókat és erőforrásokat. Az ügyfélalkalmazások ezután kéréseket küldhetnek egy szolgáltatás vagy erőforrás egy adott verziójára. A verziószámozás implementálásának több módszere is van:

  • URI-verziókezelés
  • Lekérdezésisztring-verziókezelés
  • Fejléc-verziókezelés

A lekérdezési sztring és az URI verziószámozása a legegyszerűbb. A fejléc verziószámozása jó módszer. A fejléc verziószámozása azonban nem olyan explicit és egyszerű, mint az URI-verziószámozás. Mivel az URL-verziószámozás a legegyszerűbb és leg explicitebb, az eShopOnContainers mintaalkalmazás URI-verziószámozást használ.

Az URI-verziószámozással – ahogyan az eShopOnContainers mintaalkalmazásban is – minden alkalommal, amikor módosítja a webes API-t vagy módosítja az erőforrások sémáját, minden erőforráshoz hozzáad egy verziószámot az URI-hoz. A meglévő URI-knak továbbra is a korábbiakhoz hasonlóan kell működniük, és olyan erőforrásokat kell visszaadniuk, amelyek megfelelnek a kért verziónak megfelelő sémának.

Ahogyan az alábbi kód példában látható, a verzió a Webes API-vezérlő Route attribútumával állítható be, amely explicité teszi a verziót az URI-ban (ebben az esetben v1).

[Route("api/v1/[controller]")]
public class CatalogController : ControllerBase
{
    // Implementation ...

Ez a verziószámozási mechanizmus egyszerű, és attól függ, hogy a kiszolgáló a megfelelő végpontra irányítja a kérést. A REST használata esetén azonban a kifinomultabb verziószámozáshoz és a legjobb módszerhez használja a hypermedia szolgáltatást, és implementálja a HATEOAS -t (Hypertext, mint az alkalmazásállapot motorja).

További erőforrások

Swagger-leírás metaadatainak létrehozása a ASP.NET Core Web API-ból

A Swagger egy gyakran használt nyílt forráskód keretrendszer, amelyet olyan eszközök széles körű ökoszisztémája biztosít, amelyek segítenek a RESTful API-k tervezésében, összeállításában, dokumentálásában és felhasználásában. Az API-k leíró metaadat-tartományának szabványává válik. A Swagger leírási metaadatainak tartalmaznia kell bármilyen mikroszolgáltatást, adatvezérelt mikroszolgáltatást vagy fejlettebb, tartományalapú mikroszolgáltatást (a következő szakaszban leírtak szerint).

A Swagger lényege a Swagger specifikációja, amely egy JSON- vagy YAML-fájl API-leírási metaadatai. A specifikáció létrehozza az API RESTful szerződését, amely az összes erőforrását és műveleteit emberi és gépi olvasható formátumban részletezi az egyszerű fejlesztés, a felderítés és az integráció érdekében.

A specifikáció az OpenAPI-specifikáció (OAS) alapja, és egy nyílt, transzparens és együttműködésen alapuló közösségben fejlesztették ki, hogy egységesítse a RESTful interfészek definiálásának módját.

A specifikáció meghatározza a szolgáltatás felderítési módjának és képességeinek szerkezetét. További információkért, beleértve egy webszerkesztőt és példákat a Swagger specifikációira olyan vállalatoktól, mint a Spotify, az Uber, a Slack és a Microsoft, tekintse meg a Swagger webhelyet (https://swagger.io).

Miért érdemes a Swaggert használni?

Az API-k Swagger-metaadatainak létrehozásának fő okai a következők.

Az API-k automatikus felhasználásának és integrálásának képessége más termékek számára. Több tucat termék és kereskedelmi eszköz, valamint számos kódtár és keretrendszer támogatja a Swaggert. A Microsoft olyan magas szintű termékkel és eszközökkel rendelkezik, amelyek automatikusan használhatják a Swagger-alapú API-kat, például a következőket:

API-dokumentáció automatikus létrehozásának lehetősége. Nagy méretű RESTful API-k, például összetett mikroszolgáltatás-alapú alkalmazások létrehozásakor számos végpontot kell kezelnie a kérések és válaszok hasznos adataiban használt különböző adatmodellekkel. A megfelelő dokumentáció és a Swaggerhez hasonlóan egy szilárd API-kezelő használata kulcsfontosságú az API sikeréhez és a fejlesztők általi bevezetéshez.

A Swagger metaadatait a Microsoft Flow, a PowerApps és az Azure Logic Apps használja az API-k használatának és a hozzájuk való kapcsolódásnak a megértéséhez.

A Swagger-metaadatok létrehozásának automatizálására számos lehetőség áll rendelkezésre ASP.NET Core REST API-alkalmazásokhoz funkcionális API-súgóoldalak formájában, a swagger-ui alapján.

Valószínűleg a Legjobb tudni a Swashbuckle, amelyet jelenleg az eShopOnContainersben használunk, és ebben az útmutatóban részletesen ismertetjük, de lehetőség van az NSwag használatára is, amely Typescript- és C# API-ügyfeleket, valamint C# vezérlőket hozhat létre egy Swagger- vagy OpenAPI-specifikációból, és még a vezérlőket tartalmazó .dll vizsgálatával is. NSwagStudio használatával.

Az API Swagger metaadatok létrehozásának automatizálása a Swashbuckle NuGet-csomaggal

A Swagger-metaadatok manuális létrehozása (JSON- vagy YAML-fájlban) fárasztó munka lehet. A Swashbuckle NuGet-csomag használatával azonban automatizálhatja ASP.NET webes API-szolgáltatások API-felderítését a Swagger API metaadatainak dinamikus létrehozásához.

A Swashbuckle automatikusan létrehozza a Swagger metaadatait a ASP.NET Webes API-projektekhez. Támogatja ASP.NET Core Web API-projekteket, valamint a hagyományos ASP.NET Webes API-t és bármilyen más ízt, például az Azure API Appot, az Azure Mobile Appot, az Azure Service Fabric mikroszolgáltatásokat ASP.NET alapján. Támogatja a tárolókon üzembe helyezett egyszerű webes API-t is, mint a referenciaalkalmazás esetében.

A Swashbuckle egyesíti az API Explorert és a Swagger vagy swagger-ui böngészőt , hogy gazdag felderítési és dokumentációs élményt nyújtson az API-felhasználók számára. A Swagger metaadat-generátormotorja mellett a Swashbuckle a swagger-ui beágyazott verzióját is tartalmazza, amelyet a Swashbuckle telepítése után automatikusan kiszolgál.

Ez azt jelenti, hogy kiegészítheti az API-t egy szép felderítési felhasználói felülettel, amely segít a fejlesztőknek az API használatában. Kis mennyiségű kódra és karbantartásra van szükség, mert automatikusan létrejön, így az API-ra összpontosíthat. Az API Explorer eredménye a 6–8. ábrához hasonlóan néz ki.

Képernyőkép az eShopOContainers API-t megjelenítő Swagger API Explorerről.

6-8. ábra. Swashbuckle API Explorer swagger metaadatokon alapuló – eShopOnContainers katalógus mikroszolgáltatás

A Swashbuckle által létrehozott Swagger UI API dokumentációja tartalmazza az összes közzétett műveletet. Itt nem az API Explorer a legfontosabb. Ha már rendelkezik egy olyan webes API-val, amely leírhatja magát a Swagger metaadataiban, az API zökkenőmentesen használható a Swagger-alapú eszközökből, beleértve az ügyfélproxy-osztály kódgenerátorait, amelyek számos platformot célozhatnak meg. Az AutoRest például automatikusan .NET-ügyfélosztályokat hoz létre. De további eszközök, például a swagger-codegen is elérhetők, amelyek lehetővé teszik az API-ügyfélkódtárak, a kiszolgálói csonkok és a dokumentáció automatikus kódgenerálását.

A Swashbuckle jelenleg öt belső NuGet-csomagból áll a Swashbuckle.AspNetCore magas szintű metapackage alatt ASP.NET Core-alkalmazásokhoz.

Miután telepítette ezeket a NuGet-csomagokat a webes API-projektben, konfigurálnia kell a Swaggert a Program.cs osztályban, az alábbi egyszerűsített kódhoz hasonlóan:

// Add framework services.

builder.Services.AddSwaggerGen(options =>
{
    options.DescribeAllEnumsAsStrings();
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "eShopOnContainers - Catalog HTTP API",
        Version = "v1",
        Description = "The Catalog Microservice HTTP API. This is a Data-Driven/CRUD microservice sample"
    });
});

// Other startup code...

app.UseSwagger();

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

Ha ez megtörtént, elindíthatja az alkalmazást, és a következő Swagger JSON- és UI-végpontok között tallózhat az alábbi URL-címek használatával:

  http://<your-root-url>/swagger/v1/swagger.json

  http://<your-root-url>/swagger/

Korábban a Swashbuckle által létrehozott felhasználói felületet látta egy olyan URL-címhez, mint a http://<your-root-url>/swagger. A 6–9. ábrán azt is láthatja, hogyan tesztelhet bármely API-módszert.

Képernyőkép a Swagger felhasználói felületéről, amelyen az elérhető tesztelési eszközök láthatók.

6–9. ábra. Swashbuckle felhasználói felület tesztelése a Catalog/Items API-metódusban

A Swagger UI API részletei a válasz egy mintáját jelenítik meg, és a valódi API végrehajtására használhatók, ami nagyszerű a fejlesztői felderítéshez. Ha meg szeretné tekinteni az eShopOnContainers mikroszolgáltatásból létrehozott Swagger JSON-metaadatokat (amely alatt az eszközök ezt használják), küldjön egy kérést http://<your-root-url>/swagger/v1/swagger.json a Visual Studio Code: REST Client bővítmény használatával.

További erőforrások

Előzőkövetkező