Delen via

Een eenvoudige, gegevensgestuurde CRUD-microservice maken

Aanbeveling

Deze inhoud is een fragment uit het eBook, .NET Microservices Architecture for Containerized .NET Applications, beschikbaar op .NET Docs of als een gratis downloadbare PDF die offline kan worden gelezen.

PDF downloaden

.NET Microservices Architectuur voor Gecontaineriseerde .NET Toepassingen eBook omslagthumbnail.

In deze sectie wordt beschreven hoe u een eenvoudige microservice maakt waarmee CRUD-bewerkingen (Create, Read, Update en Delete) op een gegevensbron worden uitgevoerd.

Een eenvoudige CRUD-microservice ontwerpen

Vanuit een ontwerppunt is dit type containermicroservice heel eenvoudig. Misschien is het probleem om op te lossen eenvoudig, of misschien is de implementatie slechts een bewijs van concept.

Diagram met een eenvoudig intern ontwerppatroon voor crud-microservices.

Afbeelding 6-4. Intern ontwerp voor eenvoudige CRUD-microservices

Een voorbeeld van dit soort eenvoudige gegevensstationsservice is de catalogusmicroservice uit de voorbeeldtoepassing eShopOnContainers. Dit type service implementeert alle functionaliteit in één ASP.NET Core Web API-project met klassen voor het gegevensmodel, de bedrijfslogica en de bijbehorende code voor gegevenstoegang. Ook worden de gerelateerde gegevens opgeslagen in een database die wordt uitgevoerd in SQL Server (als een andere container voor ontwikkelings-/testdoeleinden), maar kan ook elke gewone SQL Server-host zijn, zoals wordt weergegeven in afbeelding 6-5.

Diagram met een gegevensgestuurde/CRUD-microservicecontainer.

Afbeelding 6-5. Eenvoudig ontwerp voor gegevensgestuurde/CRUD-microservice

In het vorige diagram ziet u de logische catalogusmicroservice, die de catalogusdatabase bevat, die al dan niet in dezelfde Docker-host kan staan. De database in dezelfde Docker-host kan goed zijn voor ontwikkeling, maar niet voor productie. Wanneer u dit soort services ontwikkelt, hebt u alleen ASP.NET Core en een API voor gegevenstoegang of ORM nodig, zoals Entity Framework Core. U kunt ook automatisch Swagger-metagegevens genereren via Swashbuckle om een beschrijving te geven van wat uw service biedt, zoals wordt uitgelegd in de volgende sectie.

Houd er rekening mee dat het uitvoeren van een databaseserver zoals SQL Server in een Docker-container ideaal is voor ontwikkelomgevingen, omdat u al uw afhankelijkheden kunt uitvoeren zonder dat u een database hoeft in te richten in de cloud of on-premises. Deze methode is handig bij het uitvoeren van integratietests. Voor productieomgevingen wordt het uitvoeren van een databaseserver in een container echter niet aanbevolen, omdat u meestal geen hoge beschikbaarheid krijgt met die benadering. Voor een productieomgeving in Azure wordt u aangeraden Azure SQL DB of een andere databasetechnologie te gebruiken die hoge beschikbaarheid en hoge schaalbaarheid kan bieden. Voor een NoSQL-benadering kunt u bijvoorbeeld CosmosDB kiezen.

Ten slotte kunt u, door de Dockerfile- en docker-compose.yml metagegevensbestanden te bewerken, configureren hoe de installatiekopieën van deze container worden gemaakt, welke basisinstallatiekopieën worden gebruikt, plus ontwerpinstellingen zoals interne en externe namen en TCP-poorten.

Een eenvoudige CRUD-microservice implementeren met ASP.NET Core

Als u een eenvoudige CRUD-microservice wilt implementeren met .NET en Visual Studio, maakt u eerst een eenvoudig ASP.NET Core Web API-project (uitgevoerd op .NET, zodat deze kan worden uitgevoerd op een Linux Docker-host), zoals wordt weergegeven in afbeelding 6-6.

Schermopname van Visual Studios met de configuratie van het project.

Afbeelding 6-6. Een ASP.NET Core Web API-project maken in Visual Studio 2019

Als u een ASP.NET Core Web API-project wilt maken, selecteert u eerst een ASP.NET Core-webtoepassing en selecteert u vervolgens het API-type. Nadat u het project hebt gemaakt, kunt u uw MVC-controllers implementeren zoals in elk ander web-API-project, met behulp van de Entity Framework-API of andere API. In een nieuw web-API-project ziet u dat de enige afhankelijkheid die u in die microservice hebt zich bevindt op ASP.NET Core zelf. Intern, binnen de afhankelijkheid Microsoft.AspNetCore.All , verwijst het naar Entity Framework en vele andere .NET NuGet-pakketten, zoals wordt weergegeven in afbeelding 6-7.

Schermopname van VS met de NuGet-afhankelijkheden van Catalog.Api.

Afbeelding 6-7. Afhankelijkheden in een eenvoudige CRUD Web API-microservice

Het API-project bevat verwijzingen naar Microsoft.AspNetCore.App NuGet-pakket, inclusief verwijzingen naar alle essentiële pakketten. Het kan ook enkele andere pakketten bevatten.

CRUD-web-API-services implementeren met Entity Framework Core

Entity Framework (EF) Core is een lichtgewicht, uitbreidbare en platformoverschrijdende versie van de populaire Entity Framework-technologie voor gegevenstoegang. EF Core is een object-relationele mapper (ORM) waarmee .NET-ontwikkelaars met een database kunnen werken met behulp van .NET-objecten.

De catalogusmicroservice maakt gebruik van EF en de SQL Server-provider omdat de database wordt uitgevoerd in een container met de SQL Server voor Linux Docker-installatiekopieën. De database kan echter worden geïmplementeerd in elke SQL Server, zoals Windows on-premises of Azure SQL DB. Het enige wat u moet wijzigen, is de verbindingsreeks in de ASP.NET web-API-microservice.

Het gegevensmodel

Met EF Core wordt gegevenstoegang uitgevoerd met behulp van een model. Een model bestaat uit entiteitsklassen (domeinmodel) en een afgeleide context (DbContext) die een sessie met de database vertegenwoordigt, zodat u gegevens kunt opvragen en opslaan. U kunt een model genereren op basis van een bestaande database, handmatig een model codeeren dat overeenkomt met uw database of EF-migratietechnieken gebruiken om een database te maken op basis van uw model, met behulp van de code-first benadering (waarmee u de database eenvoudig kunt ontwikkelen wanneer uw model in de loop van de tijd verandert). Voor de catalogusmicroservice is de laatste methode gebruikt. In het volgende codevoorbeeld ziet u een voorbeeld van de entiteitsklasse CatalogItem. Dit is een eenvoudige POCO-entiteitsklasse (Plain Old Class Object).

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 ...
}

U hebt ook een DbContext nodig die een sessie met de database vertegenwoordigt. Voor de catalogusmicroservice is de Klasse CatalogContext afgeleid van de DbContext-basisklasse, zoals wordt weergegeven in het volgende voorbeeld:

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 ...
}

U kunt aanvullende DbContext implementaties hebben. In de microservice Catalog.API-voorbeeld ziet u bijvoorbeeld een tweede DbContext naam CatalogContextSeed waarin de voorbeeldgegevens automatisch worden ingevuld wanneer deze voor het eerst toegang probeert te krijgen tot de database. Deze methode is ook handig voor demogegevens en voor geautomatiseerde testscenario's.

Binnen de DbContextmethode gebruikt u de OnModelCreating methode om object-/databaseentiteitstoewijzingen en andere EF-uitbreidbaarheidspunten aan te passen.

Query's uitvoeren op gegevens van web-API-controllers

Exemplaren van uw entiteitsklassen worden doorgaans opgehaald uit de database met behulp van LANGUAGE-Integrated Query (LINQ), zoals wordt weergegeven in het volgende voorbeeld:

[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);
    }
    //...
}
Gegevens opslaan

Gegevens worden gemaakt, verwijderd en gewijzigd in de database met behulp van exemplaren van uw entiteitsklassen. U kunt code toevoegen zoals het volgende in code vastgelegde voorbeeld (in dit geval mockgegevens) aan uw web-API-controllers.

var catalogItem = new CatalogItem() {CatalogTypeId=2, CatalogBrandId=2,
                                     Name="Roslyn T-Shirt", Price = 12};
_context.Catalog.Add(catalogItem);
_context.SaveChanges();
Afhankelijkheidsinjectie in ASP.NET Core- en Web-API-controllers

In ASP.NET Core kunt u afhankelijkheidsinjectie (DI) uit de doos gebruiken. U hoeft geen IoC-container (Inversion of Control) van derden in te stellen, hoewel u desgewenst uw favoriete IoC-container kunt aansluiten op de ASP.NET Core-infrastructuur. In dit geval betekent dit dat u de vereiste EF DBContext of extra opslagplaatsen rechtstreeks kunt injecteren via de controllerconstructor.

In de CatalogController eerder genoemde klasse ( CatalogContext die overgaat van DbContext) type wordt samen met de andere vereiste objecten in de CatalogController() constructor geïnjecteerd.

Een belangrijke configuratie voor het instellen in het web-API-project is de DbContext-klasseregistratie in de IoC-container van de service. Dit doet u doorgaans in het Program.cs bestand door de builder.Services.AddDbContext<CatalogContext>() methode aan te roepen, zoals wordt weergegeven in het volgende vereenvoudigde voorbeeld:

// 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));
});

Belangrijk

Microsoft raadt u aan de veiligste verificatiestroom te gebruiken die beschikbaar is. Als u verbinding maakt met Azure SQL, is Managed Identities voor Azure-resources de aanbevolen verificatiemethode.

Aanvullende bronnen

De DB-verbindingsreeks- en omgevingsvariabelen die worden gebruikt door Docker-containers

U kunt de ASP.NET Core-instellingen gebruiken en een ConnectionString-eigenschap toevoegen aan uw settings.json-bestand, zoals wordt weergegeven in het volgende voorbeeld:

{
    "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"
        }
    }
}

Het bestand settings.json kan standaardwaarden hebben voor de eigenschap ConnectionString of voor een andere eigenschap. Deze eigenschappen worden echter overschreven door de waarden van omgevingsvariabelen die u in het docker-compose.override.yml-bestand opgeeft, wanneer u Docker gebruikt.

Vanuit uw docker-compose.yml- of docker-compose.override.yml-bestanden kunt u deze omgevingsvariabelen initialiseren, zodat Docker ze instelt als omgevingsvariabelen voor het besturingssysteem, zoals wordt weergegeven in het volgende docker-compose.override.yml bestand (de verbindingsreeks en andere regels in dit voorbeeld, maar deze worden niet in uw eigen bestand verpakt).

# 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"

Belangrijk

Microsoft raadt u aan de veiligste verificatiestroom te gebruiken die beschikbaar is. Als u verbinding maakt met Azure SQL, is Managed Identities voor Azure-resources de aanbevolen verificatiemethode.

De docker-compose.yml bestanden op oplossingsniveau zijn niet alleen flexibeler dan configuratiebestanden op project- of microserviceniveau, maar ook veiliger als u de omgevingsvariabelen overschrijft die zijn gedeclareerd in de docker-compose-bestanden met waarden die zijn ingesteld vanuit uw implementatiehulpprogramma's, zoals vanuit Azure DevOps Services Docker-implementatietaken.

Ten slotte kunt u die waarde ophalen uit uw code met behulp van builder.Configuration["ConnectionString"], zoals wordt weergegeven in een eerder codevoorbeeld.

Voor productieomgevingen wilt u echter mogelijk aanvullende manieren verkennen om geheimen zoals de verbindingsreeks s op te slaan. Een uitstekende manier om toepassingsgeheimen te beheren, is het gebruik van Azure Key Vault.

Azure Key Vault helpt bij het opslaan en beveiligen van cryptografische sleutels en geheimen die worden gebruikt door uw cloudtoepassingen en -services. Een geheim is alles waar u strikte controle over wilt houden, zoals API-sleutels, verbindingsreeks s, wachtwoorden, enzovoort, en strikte controle omvat gebruikslogboeken, het instellen van verlooptijd, het beheren van de toegang, onder andere.

Azure Key Vault biedt een gedetailleerd beheerniveau van het gebruik van toepassingsgeheimen zonder dat iedereen deze hoeft te laten weten. De geheimen kunnen zelfs worden gedraaid voor verbeterde beveiliging zonder de ontwikkeling of bewerkingen te verstoren.

Toepassingen moeten worden geregistreerd in de Active Directory van de organisatie, zodat ze de Key Vault kunnen gebruiken.

U kunt de key Vault-conceptendocumentatie raadplegen voor meer informatie.

Versiebeheer implementeren in ASP.NET Web-API's

Naarmate de bedrijfsvereisten veranderen, kunnen nieuwe verzamelingen resources worden toegevoegd, kunnen de relaties tussen resources veranderen en kan de structuur van de gegevens in resources worden gewijzigd. Het bijwerken van een web-API voor het afhandelen van nieuwe vereisten is een relatief eenvoudig proces, maar u moet rekening houden met de effecten die dergelijke wijzigingen hebben op clienttoepassingen die de web-API gebruiken. Hoewel de ontwikkelaar die een web-API ontwerpt en implementeert, volledige controle over die API heeft, heeft de ontwikkelaar niet dezelfde mate van controle over clienttoepassingen die kunnen worden gebouwd door externe organisaties die extern werken.

Met versiebeheer kan een web-API de functies en resources aangeven die worden weergegeven. Een clienttoepassing kan vervolgens aanvragen indienen bij een specifieke versie van een functie of resource. Er zijn verschillende manieren om versiebeheer te implementeren:

  • URI-versiebeheer
  • Versiebeheer voor querytekenreeks
  • Header-versiebeheer

Queryreeks en URI-versiebeheer zijn het eenvoudigst te implementeren. Versiebeheer van headers is een goede benadering. Versiebeheer van headers is echter niet zo expliciet en eenvoudig als URI-versiebeheer. Omdat URL-versiebeheer de eenvoudigste en meest expliciete is, maakt de voorbeeldtoepassing eShopOnContainers gebruik van URI-versiebeheer.

Met URI-versiebeheer, zoals in de voorbeeldtoepassing eShopOnContainers, voegt u telkens wanneer u de web-API wijzigt of het schema van resources wijzigt, een versienummer toe aan de URI voor elke resource. Bestaande URI's moeten net als voorheen blijven functioneren en resources retourneren die voldoen aan het schema dat overeenkomt met de aangevraagde versie.

Zoals wordt weergegeven in het volgende codevoorbeeld, kan de versie worden ingesteld met behulp van het routekenmerk in de web-API-controller, waardoor de versie expliciet wordt gemaakt in de URI (v1 in dit geval).

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

Dit versiebeheermechanisme is eenvoudig en is afhankelijk van de server die de aanvraag doorsturen naar het juiste eindpunt. Voor een geavanceerdere versiebeheer en de beste methode bij het gebruik van REST moet u echter hypermedia gebruiken en HATEOAS (Hypertext implementeren als de engine van de toepassingsstatus).

Aanvullende bronnen

Swagger-beschrijvingsmetagegevens genereren van uw ASP.NET Core-web-API

Swagger is een veelgebruikt opensource-framework dat wordt ondersteund door een groot ecosysteem van hulpprogramma's waarmee u restful API's kunt ontwerpen, bouwen, documenteren en gebruiken. Het wordt de standaard voor het metagegevensdomein van de API's beschrijving. Neem Swagger-beschrijvingsmetagegevens op met elk type microservice, gegevensgestuurde microservices of meer geavanceerde domeingestuurde microservices (zoals beschreven in de volgende sectie).

Het hart van Swagger is de Swagger-specificatie. Dit zijn API-beschrijvingsmetagegevens in een JSON- of YAML-bestand. Met de specificatie wordt het RESTful-contract voor uw API gemaakt, waarin alle resources en bewerkingen worden beschreven in een door mensen en machines leesbare indeling voor eenvoudige ontwikkeling, detectie en integratie.

De specificatie is de basis van de OpenAPI-specificatie (OAS) en is ontwikkeld in een open, transparante en gezamenlijke community om de manier waarop RESTful-interfaces worden gedefinieerd te standaardiseren.

De specificatie definieert de structuur voor hoe een service kan worden gedetecteerd en hoe de mogelijkheden ervan worden begrepen. Zie de Swagger-site (https://swagger.io) voor meer informatie, waaronder een webeditor en voorbeelden van Swagger-specificaties van bedrijven zoals Spotify, Uber, Slack en Microsoft.

Waarom Swagger gebruiken?

De belangrijkste redenen voor het genereren van Swagger-metagegevens voor uw API's zijn het volgende.

De mogelijkheid voor andere producten om uw API's automatisch te gebruiken en te integreren. Tientallen producten en commerciële hulpprogramma's en veel bibliotheken en frameworks ondersteunen Swagger. Microsoft heeft producten en hulpprogramma's op hoog niveau die automatisch Swagger-API's kunnen gebruiken, zoals de volgende:

Mogelijkheid om automatisch API-documentatie te genereren. Wanneer u grootschalige RESTful-API's maakt, zoals complexe microservicetoepassingen, moet u veel eindpunten verwerken met verschillende gegevensmodellen die worden gebruikt in de nettoladingen van aanvragen en antwoorden. Het hebben van de juiste documentatie en het hebben van een solide API-verkenner, zoals u met Swagger krijgt, is essentieel voor het succes van uw API en acceptatie door ontwikkelaars.

De metagegevens van Swagger zijn wat Microsoft Flow, PowerApps en Azure Logic Apps gebruiken om inzicht te hebben in het gebruik van API's en er verbinding mee te maken.

Er zijn verschillende opties voor het automatiseren van het genereren van Swagger-metagegevens voor ASP.NET Core REST API-toepassingen, in de vorm van functionele API-helppagina's, op basis van swagger-ui.

Waarschijnlijk het beste weten is Swashbuckle, dat momenteel wordt gebruikt in eShopOnContainers, en we behandelen een aantal details in deze handleiding, maar er is ook de optie om NSwag te gebruiken, waarmee Typescript- en C#-API-clients, evenals C#-controllers, kunnen worden gegenereerd op basis van een Swagger- of OpenAPI-specificatie en zelfs door de .dll te scannen die de controllers bevat, met NSwagStudio.

Het genereren van API Swagger-metagegevens automatiseren met het Swashbuckle NuGet-pakket

Het handmatig genereren van Swagger-metagegevens (in een JSON- of YAML-bestand) kan tijdrovend werken. U kunt de API-detectie van ASP.NET web-API-services echter automatiseren met behulp van het Swashbuckle NuGet-pakket om dynamisch Swagger API-metagegevens te genereren.

Swashbuckle genereert automatisch Swagger-metagegevens voor uw ASP.NET Web API-projecten. Het biedt ondersteuning voor ASP.NET Core Web API-projecten en de traditionele ASP.NET Web-API en elke andere smaak, zoals Azure API App, Azure Mobile App, Azure Service Fabric-microservices op basis van ASP.NET. Het biedt ook ondersteuning voor gewone web-API die is geïmplementeerd in containers, net als voor de referentietoepassing.

Swashbuckle combineert API Explorer en Swagger of swagger-ui om een uitgebreide detectie- en documentatieervaring te bieden voor uw API-consumenten. Naast de Swagger-engine voor metagegevensgenerator bevat Swashbuckle ook een ingesloten versie van swagger-ui, die automatisch wordt uitgevoerd zodra Swashbuckle is geïnstalleerd.

Dit betekent dat u uw API kunt aanvullen met een handige gebruikersinterface voor detectie, zodat ontwikkelaars uw API kunnen gebruiken. Er is een kleine hoeveelheid code en onderhoud vereist, omdat deze automatisch wordt gegenereerd, zodat u zich kunt richten op het bouwen van uw API. Het resultaat voor de API Explorer ziet eruit als afbeelding 6-8.

Schermopname van Swagger API Explorer met eShopOContainers-API.

Afbeelding 6-8. Swashbuckle API Explorer op basis van Swagger-metagegevens- eShopOnContainers-catalogus microservice

De door Swashbuckle gegenereerde Swagger UI API-documentatie bevat alle gepubliceerde acties. De API Explorer is hier niet het belangrijkste. Zodra u een web-API hebt die zichzelf kan beschrijven in Swagger-metagegevens, kan uw API naadloos worden gebruikt vanuit hulpprogramma's op basis van Swagger, waaronder codegeneratoren van clientproxyklasse die op veel platforms kunnen worden gericht. Zoals vermeld, genereert AutoRest bijvoorbeeld automatisch .NET-clientklassen. Er zijn echter ook extra hulpprogramma's zoals swagger-codegen beschikbaar, waardoor het automatisch genereren van code van API-clientbibliotheken, server-stubs en documentatie mogelijk is.

Momenteel bestaat Swashbuckle uit vijf interne NuGet-pakketten onder de metapackage Swashbuckle.AspNetCore op hoog niveau voor ASP.NET Core-toepassingen.

Nadat u deze NuGet-pakketten in uw web-API-project hebt geïnstalleerd, moet u Swagger configureren in de klasse Program.cs , zoals in de volgende vereenvoudigde code:

// 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");
    });
}

Zodra dit is gebeurd, kunt u uw toepassing starten en door de volgende Swagger JSON- en UI-eindpunten bladeren met behulp van URL's zoals deze:

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

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

U hebt eerder de gegenereerde gebruikersinterface gezien die door Swashbuckle is gemaakt voor een URL zoals http://<your-root-url>/swagger. In afbeelding 6-9 kunt u ook zien hoe u elke API-methode kunt testen.

Schermopname van de Swagger-gebruikersinterface met beschikbare testhulpprogramma's.

Afbeelding 6-9. Swashbuckle-gebruikersinterface die de API-methode Catalog/Items test

De details van de Swagger UI-API tonen een voorbeeld van het antwoord en kunnen worden gebruikt om de echte API uit te voeren. Dit is ideaal voor detectie van ontwikkelaars. Als u de Swagger JSON-metagegevens wilt zien die zijn gegenereerd op basis van de microservice eShopOnContainers (wat de hulpprogramma's hieronder gebruiken), dient u een aanvraag uit te voeren http://<your-root-url>/swagger/v1/swagger.json met behulp van de Visual Studio Code: REST Client-extensie.

Aanvullende bronnen

VorigeVolgende

  • Last updated on