Een web-API maken met ASP.NET Core en MongoDB

Door Pratik Khandelwal en Scott Addie

In deze zelfstudie maakt u een web-API die CRUD-bewerkingen (Create, Read, Update en Delete) uitvoert op een MongoDB NoSQL-database.

In deze zelfstudie leert u het volgende:

• MongoDB configureren
• Een MongoDB-database maken
• Een MongoDB-verzameling en -schema definiëren
• MongoDB CRUD-bewerkingen uitvoeren vanuit een web-API
• JSON-serialisatie aanpassen

Vereiste voorwaarden

• MongoDB 6.0.5 of hoger
• MongoDB Shell

Visual Studio

• Visual Studio 2022 met de workload voor ASP.NET en webontwikkeling.

  

Visual Studio Code

• Visual Studio Code
• C# Dev Kit voor Visual Studio Code
• .NET 9 SDK

U kunt de Visual Studio Code-instructies volgen voor macOS, Linux of Windows. Mogelijk zijn er wijzigingen vereist als u een andere IDE (Integrated Development Environment) dan Visual Studio Code gebruikt.

MongoDB configureren

MongoDB- en MongoDB Shell-toegang vanaf elke locatie op de ontwikkelcomputer inschakelen (Windows/Linux/macOS):

1. MongoDB Shell downloaden en installeren:

   • macOS/Linux: kies een map waarin u de MongoDB-shell wilt extraheren. Voeg het resulterende pad voor mongosh aan de PATH omgevingsvariabele toe.
   • Windows: MongoDB Shell (mongosh.exe) is geïnstalleerd op C:\Users\user<\>AppData\Local\Programs\mongosh. Voeg het resulterende pad voor mongosh.exe aan de PATH omgevingsvariabele toe.

2. MongoDB downloaden en installeren:

   • macOS/Linux: Controleer de map waarin MongoDB is geïnstalleerd, meestal in /usr/local/mongodb. Voeg het resulterende pad voor mongodb aan de PATH omgevingsvariabele toe.
   • Windows: MongoDB is standaard geïnstalleerd op C:\Program Files\MongoDB . Voeg C:\Program Files\MongoDB\Server\<version_number>\bin toe aan de PATH omgevingsvariabele.

3. Kies een gegevensopslagmap: selecteer een map op uw ontwikkelcomputer voor het opslaan van gegevens. Maak de map aan, als deze niet bestaat. Met de MongoDB-shell worden geen nieuwe mappen gemaakt:

   • macOS/Linux: bijvoorbeeld /usr/local/var/mongodb.
   • Windows: bijvoorbeeld C:\\BooksData.

4. Gebruik in de opdrachtshell van het besturingssysteem (niet de MongoDB-shell) de volgende opdracht om verbinding te maken met MongoDB op standaardpoort 27017. Vervang <data_directory_path> door de map die u in de vorige stap hebt gekozen.

   mongod --dbpath <data_directory_path>
   

Gebruik de eerder geïnstalleerde MongoDB Shell in de volgende stappen om een database te maken, verzamelingen te maken en documenten op te slaan. Zie voor meer informatie over MongoDB Shell-opdrachten mongosh.

1. Open een MongoDB-opdrachtshell-exemplaar door het starten mongosh.exeof door de volgende opdracht uit te voeren in de opdrachtshell:

   mongosh
   

2. Maak in de opdrachtshell verbinding met de standaardtestdatabase door het volgende uit te voeren:

   use BookStore
   

   Er wordt een database met de naam BookStore gemaakt als deze nog niet bestaat. Als de database wel bestaat, wordt de verbinding geopend voor transacties.

3. Maak een Books verzameling met behulp van de volgende opdracht:

   db.createCollection('Books')
   

   Het volgende resultaat wordt weergegeven:

   { "ok" : 1 }
   

4. Definieer een schema voor de Books verzameling en voeg twee documenten in met behulp van de volgende opdracht:

   db.Books.insertMany([{ "Name": "Design Patterns", "Price": 54.93, "Category": "Computers", "Author": "Ralph Johnson" }, { "Name": "Clean Code", "Price": 43.15, "Category": "Computers","Author": "Robert C. Martin" }])
   

   Er wordt een resultaat weergegeven dat lijkt op het volgende:

   {
       "acknowledged" : true,
       "insertedIds" : [
           ObjectId("61a6058e6c43f32854e51f51"),
           ObjectId("61a6058e6c43f32854e51f52")
        ]
    }
   

   Opmerking

   De ObjectIdin het voorgaande resultaat weergegeven resultaten komen niet overeen met de resultaten die worden weergegeven in de opdrachtshell.

5. Bekijk de documenten in de database met behulp van de volgende opdracht:

   db.Books.find().pretty()
   

   Er wordt een resultaat weergegeven dat lijkt op het volgende:

   {
        "_id" : ObjectId("61a6058e6c43f32854e51f51"),
        "Name" : "Design Patterns",
        "Price" : 54.93,
        "Category" : "Computers",
        "Author" : "Ralph Johnson"
    }
    {
        "_id" : ObjectId("61a6058e6c43f32854e51f52"),
        "Name" : "Clean Code",
        "Price" : 43.15,
        "Category" : "Computers",
        "Author" : "Robert C. Martin"
    }
   

   Het schema voegt een automatisch gegenereerde _id eigenschap van het type ObjectId toe voor elk document.

Het ASP.NET Core-web-API-project maken

Visual Studio

1. Ga naar Bestand>Nieuw>Project.
2. Selecteer het projecttype ASP.NET Core Web API en selecteer Volgende.
3. Geef het project de naam BookStoreApi en selecteer Volgende.
4. In het dialoogvenster Aanvullende informatie:

• Controleer of de Framework is .NET 9.0 (Standaardterm Ondersteuning).
• Controleer of het selectievakje voor Controllers gebruiken is ingeschakeld.
• Controleer of het selectievakje voor OpenAPI-ondersteuning inschakelen is ingeschakeld.
• Klik op Creëren.

1. Navigeer in het Package Manager Console-venster naar de hoofdmap van het project. Voer de volgende opdracht uit om het .NET-stuurprogramma voor MongoDB te installeren:

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. Voer de volgende opdrachten uit in een opdrachtshell:

   dotnet new webapi -o BookStoreApi --use-controllers
   code BookStoreApi
   

   Met de voorgaande opdrachten wordt een nieuw ASP.NET Core-web-API-project gegenereerd en vervolgens het project geopend in Visual Studio Code.

2. Zodra de OmniSharp-server is gestart, wordt in een dialoogvenster de vereiste assets gevraagd om te bouwen en fouten op te sporen in 'BookStoreApi'. Voeg ze toe? Selecteer Ja.

3. Open de Integrated Terminal en voer de volgende opdracht uit om het .NET-stuurprogramma voor MongoDB te installeren:

   dotnet add package MongoDB.Driver
   

Een entiteitsmodel toevoegen

1. Voeg een Models-map toe aan de hoofdmap van het project.

2. Voeg een Book klasse toe aan de map Modellen met de volgende code:

   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   
   namespace BookStoreApi.Models;
   
   public class Book
   {
       [BsonId]
       [BsonRepresentation(BsonType.ObjectId)]
       public string? Id { get; set; }
   
       [BsonElement("Name")]
       public string BookName { get; set; } = null!;
   
       public decimal Price { get; set; }
   
       public string Category { get; set; } = null!;
   
       public string Author { get; set; } = null!;
   }
   

   In de voorgaande klasse is de Id eigenschap:

   • Vereist voor het toewijzen van het CLR-object (Common Language Runtime) aan de MongoDB-verzameling.
   • Aangewezen met [BsonId] om van deze eigenschap de primaire sleutel van het document te maken.
   • Geannoteerd met [BsonRepresentation(BsonType.ObjectId)] zodat de parameter kan worden doorgegeven als type string in plaats van een ObjectId-structuur. Mongo verwerkt de conversie van string naar ObjectId.

   De BookName eigenschap wordt geannoteerd met het [BsonElement] kenmerk. De waarde van het kenmerk Name vertegenwoordigt de eigenschapsnaam in de MongoDB-verzameling.

Een configuratiemodel toevoegen

1. Voeg de volgende databaseconfiguratiewaarden toe aan appsettings.json:

   {
     "BookStoreDatabase": {
       "ConnectionString": "mongodb://localhost:27017",
       "DatabaseName": "BookStore",
       "BooksCollectionName": "Books"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

2. Voeg een BookStoreDatabaseSettings klasse toe aan de map Modellen met de volgende code:

   namespace BookStoreApi.Models;
   
   public class BookStoreDatabaseSettings
   {
       public string ConnectionString { get; set; } = null!;
   
       public string DatabaseName { get; set; } = null!;
   
       public string BooksCollectionName { get; set; } = null!;
   }
   

   De voorgaande BookStoreDatabaseSettings klasse wordt gebruikt om de eigenschapswaarden van appsettings.json het BookStoreDatabase bestand op te slaan. De namen van de JSON- en C#-eigenschappen zijn identiek om het koppelingproces te vereenvoudigen.

3. Voeg de volgende gemarkeerde code toe aan Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   

   In de voorgaande code wordt het configuratie-exemplaar waaraan de sectie van het appsettings.json bestand is gekoppeld, geregistreerd in de Dependency Injection (DI) container. De BookStoreDatabaseSettings eigenschap van het ConnectionString object wordt bijvoorbeeld gevuld met de BookStoreDatabase:ConnectionString eigenschap in appsettings.json.

4. Voeg de volgende code toe bovenaan Program.cs om de BookStoreDatabaseSettings verwijzing op te lossen:

   using BookStoreApi.Models;
   

Een CRUD-bewerkingsservice toevoegen

1. Voeg een Services-directory toe aan de hoofdmap van het project.

2. Voeg een BooksService klasse toe aan de Services directory met de volgende code:

   using BookStoreApi.Models;
   using Microsoft.Extensions.Options;
   using MongoDB.Driver;
   
   namespace BookStoreApi.Services;
   
   public class BooksService
   {
       private readonly IMongoCollection<Book> _booksCollection;
   
       public BooksService(
           IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
       {
           var mongoClient = new MongoClient(
               bookStoreDatabaseSettings.Value.ConnectionString);
   
           var mongoDatabase = mongoClient.GetDatabase(
               bookStoreDatabaseSettings.Value.DatabaseName);
   
           _booksCollection = mongoDatabase.GetCollection<Book>(
               bookStoreDatabaseSettings.Value.BooksCollectionName);
       }
   
       public async Task<List<Book>> GetAsync() =>
           await _booksCollection.Find(_ => true).ToListAsync();
   
       public async Task<Book?> GetAsync(string id) =>
           await _booksCollection.Find(x => x.Id == id).FirstOrDefaultAsync();
   
       public async Task CreateAsync(Book newBook) =>
           await _booksCollection.InsertOneAsync(newBook);
   
       public async Task UpdateAsync(string id, Book updatedBook) =>
           await _booksCollection.ReplaceOneAsync(x => x.Id == id, updatedBook);
   
       public async Task RemoveAsync(string id) =>
           await _booksCollection.DeleteOneAsync(x => x.Id == id);
   }
   

   In de voorgaande code wordt een BookStoreDatabaseSettings exemplaar opgehaald uit DI via constructorinjectie. Deze techniek biedt toegang tot de appsettings.json configuratiewaarden die zijn toegevoegd in de sectie Een configuratiemodel toevoegen .

3. Voeg de volgende gemarkeerde code toe aan Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   

   In de voorgaande code wordt de BooksService klasse geregistreerd bij DI ter ondersteuning van constructorinjectie in verbruiksklassen. De levensduur van de singleton-service is het meest geschikt omdat BooksService een directe afhankelijkheid van MongoClient heeft. Volgens de officiële richtlijnen voor hergebruik van Mongo-clients moet MongoClient worden geregistreerd in DI met een levensduur als een singleton-service.

4. Voeg de volgende code toe bovenaan Program.cs om de BooksService verwijzing op te lossen:

   using BookStoreApi.Services;
   

De BooksService klasse gebruikt de volgende MongoDB.Driver leden om CRUD-bewerkingen uit te voeren op de database:

• MongoClient: leest een serverexemplaar voor het uitvoeren van databasebewerkingen. De constructor van deze klasse wordt geleverd in de MongoDB-verbindingsreeks:

  public BooksService(
      IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
  {
      var mongoClient = new MongoClient(
          bookStoreDatabaseSettings.Value.ConnectionString);
  
      var mongoDatabase = mongoClient.GetDatabase(
          bookStoreDatabaseSettings.Value.DatabaseName);
  
      _booksCollection = mongoDatabase.GetCollection<Book>(
          bookStoreDatabaseSettings.Value.BooksCollectionName);
  }
  

• IMongoDatabase: Vertegenwoordigt de Mongo-database voor het uitvoeren van bewerkingen. In deze zelfstudie wordt gebruikgemaakt van de algemene Methode GetCollection<TDocument>(collection) op de interface om toegang te krijgen tot gegevens in een specifieke verzameling. Voer CRUD-bewerkingen uit op de verzameling nadat deze methode is aangeroepen. In de GetCollection<TDocument>(collection) methode-aanroep:

  • collection vertegenwoordigt de naam van de verzameling.
  • TDocument vertegenwoordigt het CLR-objecttype dat is opgeslagen in de verzameling.

GetCollection<TDocument>(collection) retourneert een MongoCollection-object dat de verzameling vertegenwoordigt. In deze handleiding worden de volgende methoden aangeroepen voor de verzameling:

• DeleteOneAsync: Hiermee verwijdert u één document dat overeenkomt met de opgegeven zoekcriteria.
• Vinden<TDocument>: retourneert alle documenten in de verzameling die overeenkomen met de opgegeven zoekcriteria.
• InsertOneAsync: Voegt het opgegeven object in als een nieuw document in de verzameling.
• ReplaceOneAsync: vervangt het document dat overeenkomt met de opgegeven zoekcriteria door het opgegeven object.

Een controller toevoegen

Voeg een BooksController klasse toe aan de map Controllers met de volgende code:

using BookStoreApi.Models;
using BookStoreApi.Services;
using Microsoft.AspNetCore.Mvc;

namespace BookStoreApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private readonly BooksService _booksService;

    public BooksController(BooksService booksService) =>
        _booksService = booksService;

    [HttpGet]
    public async Task<List<Book>> Get() =>
        await _booksService.GetAsync();

    [HttpGet("{id:length(24)}")]
    public async Task<ActionResult<Book>> Get(string id)
    {
        var book = await _booksService.GetAsync(id);

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

        return book;
    }

    [HttpPost]
    public async Task<IActionResult> Post(Book newBook)
    {
        await _booksService.CreateAsync(newBook);

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

    [HttpPut("{id:length(24)}")]
    public async Task<IActionResult> Update(string id, Book updatedBook)
    {
        var book = await _booksService.GetAsync(id);

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

        updatedBook.Id = book.Id;

        await _booksService.UpdateAsync(id, updatedBook);

        return NoContent();
    }

    [HttpDelete("{id:length(24)}")]
    public async Task<IActionResult> Delete(string id)
    {
        var book = await _booksService.GetAsync(id);

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

        await _booksService.RemoveAsync(id);

        return NoContent();
    }
}

De voorgaande web-API-controller:

• Gebruikt de BooksService klasse om CRUD-bewerkingen uit te voeren.
• Bevat actiemethoden ter ondersteuning van HTTP-aanvragen voor GET-, POST-, PUT- en DELETE-aanvragen.
• Roept CreatedAtAction de Create actiemethode aan om een HTTP 201-antwoord te retourneren. Statuscode 201 is het standaardantwoord voor een HTTP POST-methode waarmee een nieuwe resource op de server wordt gemaakt. CreatedAtAction voegt ook een Location header toe aan het antwoord. De Location header geeft de URI van het zojuist gemaakte boek op.

Opties voor JSON-serialisatie configureren

Er zijn twee details die moeten worden gewijzigd over de JSON-antwoorden die worden geretourneerd in de sectie De web-API testen:

• De standaard camelCase van de eigenschapsnamen moet worden gewijzigd zodat deze overeenkomt met de PascalCase van de eigenschapsnamen van het CLR-object.
• De bookName eigenschap moet worden geretourneerd als Name.

Breng de volgende wijzigingen aan om aan de voorgaande vereisten te voldoen:

1. In Program.cs, schakel de volgende gemarkeerde code aan de AddControllers methodeaanroep:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   
   builder.Services.AddControllers()
       .AddJsonOptions(
           options => options.JsonSerializerOptions.PropertyNamingPolicy = null);
   

   Met de voorgaande wijziging komen eigenschapsnamen in het geserialiseerde JSON-antwoord van de web-API overeen met de bijbehorende eigenschapsnamen in het CLR-objecttype. De Book-eigenschap van de Author-klasse serialiseert bijvoorbeeld als Author in plaats van author.

2. Annoteren in Models/Book.cs de BookName eigenschap met het [JsonPropertyName] kenmerk:

   [BsonElement("Name")]
   [JsonPropertyName("Name")]
   public string BookName { get; set; } = null!;
   

   De waarde van het [JsonPropertyName] kenmerk Name vertegenwoordigt de eigenschapsnaam in de geseraliseerde JSON-reactie van de web-API.

3. Voeg de volgende code toe bovenaan Models/Book.cs om de [JsonProperty] kenmerkreferentie op te lossen:

   using System.Text.Json.Serialization;
   

4. Herhaal de stappen die zijn gedefinieerd in de sectie De web-API testen. Let op het verschil in JSON-eigenschapsnamen.

De web-API testen

Visual Studio

In deze zelfstudie worden Endpoints Explorer- en HTTP-bestanden gebruikt om de API te testen.

1. Bouw en voer de app uit.

2. Klik in Endpoints Explorer met de rechtermuisknop op het eerste GET-eindpunt/api/booksen selecteer Aanvraag genereren.

   De volgende inhoud wordt toegevoegd aan het BookStoreApi.http bestand. Als dit de eerste keer is dat een aanvraag wordt gegenereerd, wordt het bestand gemaakt in de hoofdmap van het project.

   @BookStoreApi_HostAddress = https://localhost:<port>
   
   GET {{BookStoreApi_HostAddress}}/api/books
   
   ###
   

   Het poortnummer moet al zijn ingesteld op de poort die wordt gebruikt door de app, https://localhost:56874bijvoorbeeld. Als dat niet het geval is, kunt u uw poortnummer vinden in het uitvoervenster wanneer u de app start.

3. Selecteer de koppeling Aanvraag verzenden boven de nieuwe GET aanvraagregel.

   De GET-aanvraag wordt verzonden naar de app en het antwoord wordt weergegeven in het deelvenster Antwoord .

4. In de hoofdtekst van het antwoord ziet u het JSON-resultaat met de boekvermeldingen die er ongeveer als volgt uitzien:

   [
     {
       "Id": "61a6058e6c43f32854e51f51",
       "Name": "Design Patterns",
       "Price": 54.93,
       "Category": "Computers",
       "Author": "Ralph Johnson"
     },
     {
       "Id": "61a6058e6c43f32854e51f52",
       "Name": "Clean Code",
       "Price": 43.15,
       "Category": "Computers",
       "Author": "Robert C. Martin"
     }
   ]
   

5. Als u één boek wilt ophalen, klikt u met de rechtermuisknop op het /api/books/{id}, params (string id)GET-eindpunt in Endpoints Explorer en selecteert u Een aanvraag genereren.

   De volgende inhoud wordt toegevoegd aan het BookStoreApi.http bestand:

   @id=string
   GET {{BookStoreApi_HostAddress}}/api/books/{{id}}
   
   ###
   

6. Vervang id de variabele door een van de id's die zijn geretourneerd door de eerdere aanvraag, bijvoorbeeld:

   @id="61a6058e6c43f32854e51f52"
   GET {{BookStoreApi_HostAddress}}/api/books/{{id}}
   
   ###
   

7. Selecteer de koppeling Aanvraag verzenden boven de nieuwe GET aanvraagregel.

   De GET-aanvraag wordt verzonden naar de app en het antwoord wordt weergegeven in het deelvenster Antwoord .

8. In de hoofdtekst van het antwoord ziet u JSON die vergelijkbaar is met het volgende:

   {
     "Id": "61a6058e6c43f32854e51f52",
     "Name": "Clean Code",
     "Price": 43.15,
     "Category": "Computers",
     "Author": "Robert C. Martin"
   }
   

9. Als u het POST-eindpunt wilt testen, klikt u met de rechtermuisknop op het /api/booksPOST-eindpunt en selecteert u Aanvraag genereren.

   De volgende inhoud wordt toegevoegd aan het BookStoreApi.http-bestand:

   POST {{BookStoreApi_HostAddress}}/api/books
   Content-Type: application/json
   
   {
     //Book
   }
   
   ###
   

10. Vervang de opmerking Boek door een boekobject als de hoofdtekst van de JSON-aanvraag:

    POST {{BookStoreApi_HostAddress}}/api/books
    Content-Type: application/json
    
     {
       "Name": "The Pragmatic Programmer",
       "Price": 49.99,
       "Category": "Computers",
       "Author": "Andy Hunt"
     }
    
    ###
    

11. Selecteer de koppeling Aanvraag verzenden boven de POST aanvraagregel.

    De POST-aanvraag wordt verzonden naar de app en het antwoord wordt weergegeven in het deelvenster Antwoord . Het antwoord moet het zojuist gemaakte boek bevatten met de toegewezen ID.

12. Als u ten slotte een boek wilt verwijderen, klikt u met de rechtermuisknop op het /api/books/{id}, params (string id) eindpunt VERWIJDEREN en selecteert u Aanvraag genereren.

    De volgende inhoud wordt toegevoegd aan het BookStoreApi.http bestand:

    DELETE {{BookStoreApi_HostAddress}}/api/Books/{{id}}
    
    ###
    

13. Vervang de id variabele door een van de id's die zijn geretourneerd uit de eerdere aanvraag en klik op Aanvraag verzenden. Voorbeeld:

    DELETE {{BookStoreApi_HostAddress}}/api/Books/67f417517ce1b36aeab71236
    
    ###
    

Visual Studio Code

In deze zelfstudie worden de OpenAPI-specificatie (openapi.json) en de Swagger-gebruikersinterface gebruikt om de API te testen.

1. Installeer de Swagger-gebruikersinterface door de volgende opdracht uit te voeren:

dotnet add package NSwag.AspNetCore

Met de vorige opdracht wordt het NSwag.AspNetCore-pakket toegevoegd, dat hulpprogramma's bevat voor het genereren van Swagger-documenten en de gebruikersinterface. Omdat ons project OpenAPI gebruikt, gebruiken we alleen het NSwag-pakket om de Swagger-gebruikersinterface te genereren.

1. Het configureren van Swagger-middleware

Voeg in Program.csde volgende gemarkeerde code toe:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });
}

Met de vorige code wordt de Swagger middleware ingeschakeld voor het leveren van het gegenereerde JSON-document met behulp van de Swagger-gebruikersinterface. Swagger is alleen ingeschakeld in een ontwikkelomgeving. Het inschakelen van Swagger in een productieomgeving kan mogelijk gevoelige details over de structuur en implementatie van de API beschikbaar maken.

De app maakt gebruik van het OpenAPI-document dat is gegenereerd door OpenApi, dat zich in /openapi/v1.jsonbevindt, om de gebruikersinterface te genereren. Bekijk de gegenereerde OpenAPI-specificatie voor de WeatherForecast-API terwijl het project wordt uitgevoerd door te navigeren naar https://localhost:<port>/openapi/v1.json in uw browser.

De OpenAPI-specificatie is een document in JSON-indeling waarin de structuur en mogelijkheden van uw API worden beschreven, waaronder eindpunten, aanvraag-/antwoordindelingen, parameters en meer. Het is in wezen een blauwdruk van uw API die kan worden gebruikt door verschillende hulpprogramma's om uw API te begrijpen en ermee te communiceren.

1. Bouw en voer de app uit.

2. Ga in uw browser naar https://localhost:<port>/swagger. Swagger biedt een gebruikersinterface voor het testen van alle API-eindpunten op basis van het OpenAPI-document.

3. Vouw het eindpunt GET /api/books uit en klik op de knop Uitproberen .

4. Klik op de knop Uitvoeren om de aanvraag naar de API te verzenden.

5. In de sectie Antwoordtekst wordt een JSON-matrix met boeken weergegeven die er ongeveer als volgt uitzien:

   [
     {
       "Id": "61a6058e6c43f32854e51f51",
       "Name": "Design Patterns",
       "Price": 54.93,
       "Category": "Computers",
       "Author": "Ralph Johnson"
     },
     {
       "Id": "61a6058e6c43f32854e51f52",
       "Name": "Clean Code",
       "Price": 43.15,
       "Category": "Computers",
       "Author": "Robert C. Martin"
     }
   ]
   

6. Vouw vervolgens het EINDPUNT GET /api/books/{id} uit en klik op Uitproberen.

7. Voer een van de boek-id's uit het vorige antwoord in het id-veld in en klik vervolgens op Uitvoeren.

8. In de sectie Antwoordtekst wordt het JSON-object voor het opgegeven boek weergegeven. Het resultaat voor de id 61a6058e6c43f32854e51f52 is bijvoorbeeld vergelijkbaar met het volgende:

   {
     "Id": "61a6058e6c43f32854e51f52",
     "Name": "Clean Code",
     "Price": 43.15,
     "Category": "Computers",
     "Author": "Robert C. Martin"
   }
   

9. Als u het maken van een nieuw boek wilt testen, vouwt u het EINDPUNT POST/api/books uit en klikt u op Uitproberen.

10. Vervang de standaard inhoud van de aanvraag door een nieuw boekobject:

    {
      "Name": "The Pragmatic Programmer",
      "Price": 49.99,
      "Category": "Computers",
      "Author": "Andy Hunt"
    }
    

11. Klik op Uitvoeren om de aanvraag te verzenden.

12. Het antwoord moet de statuscode 201 (Gemaakt) hebben en het zojuist gemaakte boek opnemen met de toegewezen ID in de antwoordtekst.

13. Als u ten slotte een boekrecord wilt verwijderen, vouwt u het eindpunt DELETE /api/books/{id} uit, klikt u op Uitproberen en voert u een van de boek-id's uit het vorige antwoord in het id-veld in. Klik op Uitvoeren om de aanvraag te verzenden.

14. Het antwoord moet de statuscode 204 (Geen inhoud) hebben, waarmee wordt aangegeven dat het boek is verwijderd.

Verificatieondersteuning toevoegen aan een web-API

ASP.NET Core Identity voegt de aanmeldingsfunctionaliteit van de gebruikersinterface (UI) toe aan ASP.NET Core-web-apps. Gebruik een van de volgende manieren om web-API's en SPA's te beveiligen:

• Microsoft Entra-id
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server is een OpenID Connect- en OAuth 2.0-framework voor ASP.NET Core. Duende Identity Server maakt de volgende beveiligingsfuncties mogelijk:

• Verificatie als een service (AaaS)
• Eenmalige aanmelding/uit (SSO) voor meerdere toepassingstypen
• Toegangsbeheer voor API's
• Federatie-gateway

Belangrijk

Duende Software moet u mogelijk een licentiekosten betalen voor productiegebruik van Duende Identity Server. Zie Migreren van ASP.NET Core in .NET 5 naar .NET 6 voor meer informatie.

Zie de Duende Identity Server-documentatie (Duende Software-website)voor meer informatie.

Aanvullende bronnen

• Voorbeeldcode bekijken of downloaden (hoe download je)
• Web-API's maken met ASP.NET Core-
• Controlleractie-retourtypen in ASP.NET Core web API
• Een web-API maken met ASP.NET Core