Tworzenie internetowego interfejsu API przy użyciu platformy ASP.NET Core i bazy danych MongoDB

Przez Pratik Khandelwal i Scott Addie

W tym samouczku tworzony jest webowy interfejs API, który wykonuje operacje tworzenia, odczytu, aktualizacji i usuwania (CRUD) w bazie danych NoSQL MongoDB.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

• Konfigurowanie bazy danych MongoDB
• Tworzenie bazy danych MongoDB
• Definiowanie kolekcji i schematu bazy danych MongoDB
• Wykonywanie operacji CRUD bazy danych MongoDB z internetowego interfejsu API
• Dostosowywanie serializacji JSON

Wymagania wstępne

• MongoDB w wersji 6.0.5 lub nowszej
• Powłoka bazy danych MongoDB

Visual Studio

• Program Visual Studio 2022 z pakietem roboczym tworzenia aplikacji ASP.NET i aplikacji internetowych.

  

Visual Studio Code

• Visual Studio Code
• Zestaw deweloperski języka C# dla programu Visual Studio Code
• Zestaw SDK platformy .NET 9

Możesz postępować zgodnie z instrukcjami programu Visual Studio Code w systemach macOS, Linux lub Windows. Zmiany mogą być wymagane, jeśli używasz zintegrowanego środowiska projektowego (IDE) innego niż Visual Studio Code.

Konfigurowanie bazy danych MongoDB

Włącz dostęp do MongoDB i MongoDB Shell z dowolnego miejsca na komputerze programistycznym (Windows/Linux/macOS):

1. Pobierz i zainstaluj powłokę MongoDB

   • macOS/Linux: Wybierz katalog, do którego chcesz wyodrębnić powłokę MongoDB. Dodaj wynikową ścieżkę dla mongosh do zmiennej środowiskowej PATH.
   • Windows: MongoDB Shell (mongosh.exe) jest zainstalowany w C:\Users\<user>\AppData\Local\Programs\mongosh. Dodaj wynikową ścieżkę dla mongosh.exe do zmiennej środowiskowej PATH.

2. Pobierz i zainstaluj bazę danych MongoDB:

   • macOS/Linux: sprawdź katalog, w którym zainstalowano bazę danych MongoDB, zwykle w katalogu /usr/local/mongodb. Dodaj wynikową ścieżkę dla mongodb do zmiennej środowiskowej PATH.
   • Windows: baza danych MongoDB jest instalowana domyślnie w folderze C:\Program Files\MongoDB . Dodaj C:\Program Files\MongoDB\Server\<version_number>\bin do zmiennej środowiskowej PATH .

3. Wybierz katalog magazynu danych: wybierz katalog na maszynie programistycznej do przechowywania danych. Utwórz katalog, jeśli nie istnieje. Powłoka bazy danych MongoDB nie tworzy nowych katalogów:

   • macOS/Linux: na przykład /usr/local/var/mongodb.
   • Windows: na przykład C:\\BooksData.

4. W powłoce poleceń systemu operacyjnego (a nie w powłoce bazy danych MongoDB) użyj następującego polecenia, aby nawiązać połączenie z bazą danych MongoDB na domyślnym porcie 27017. Zastąp <data_directory_path> element katalogiem wybranym w poprzednim kroku.

   mongod --dbpath <data_directory_path>
   

Użyj wcześniej zainstalowanej powłoki MongoDB w poniższych krokach, aby utworzyć bazę danych, stworzyć kolekcje i zarchiwizować dokumenty. Aby uzyskać więcej informacji na temat poleceń powłoki bazy danych MongoDB, zobacz mongosh.

1. Otwórz wystąpienie powłoki poleceń bazy danych MongoDB, uruchamiając mongosh.exe lub poprzez wpisanie następującego polecenia w powłoce poleceń:

   mongosh
   

2. W powłoce poleceń połącz się z domyślną bazą danych testowych, uruchamiając polecenie:

   use BookStore
   

   Baza danych o nazwie BookStore jest tworzona, jeśli jeszcze nie istnieje. Jeśli baza danych istnieje, jego połączenie jest otwarte dla transakcji.

3. Books Utwórz kolekcję przy użyciu następującego polecenia:

   db.createCollection('Books')
   

   Zostanie wyświetlony następujący wynik:

   { "ok" : 1 }
   

4. Zdefiniuj schemat kolekcji Books i wstaw dwa dokumenty przy użyciu następującego polecenia:

   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" }])
   

   Zostanie wyświetlony wynik podobny do następującego:

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

   Uwaga

   Wartości ObjectIdpokazane w poprzednim wyniku nie będą zgodne z wartościami wyświetlanymi w powłoce poleceń.

5. Wyświetl dokumenty w bazie danych przy użyciu następującego polecenia:

   db.Books.find().pretty()
   

   Zostanie wyświetlony wynik podobny do następującego:

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

   Schemat dodaje automatycznie wygenerowaną _id właściwość typu ObjectId dla każdego dokumentu.

Tworzenie projektu internetowego interfejsu API platformy ASP.NET Core

Visual Studio

1. Przejdź do Plik>Nowy>Projekt.
2. Wybierz typ projektu internetowego interfejsu API platformy ASP.NET Core, a następnie wybierz pozycję Dalej.
3. Nadaj projektowi nazwę BookStoreApi, a następnie wybierz pozycję Dalej.
4. W oknie dialogowym Dodatkowe informacje:

• Upewnij się, że platforma jest .NET 9.0 (Standardowe wsparcie).
• Upewnij się, że pole wyboru Użyj kontrolerów jest zaznaczone.
• Upewnij się, że zaznaczono pole wyboru Włącz obsługę interfejsu OpenAPI.
• Wybierz Utwórz.

1. W oknie Konsoli Menedżera pakietów przejdź do katalogu głównego projektu. Uruchom następujące polecenie, aby zainstalować sterownik platformy .NET dla bazy danych MongoDB:

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. Uruchom następujące polecenia w konsoli:

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

   Powyższe polecenia generują nowy projekt internetowego interfejsu API platformy ASP.NET Core, a następnie otwierają projekt w programie Visual Studio Code.

2. Po uruchomieniu serwera OmniSharp zostanie wyświetlone okno dialogowe z pytaniem Wymagane zasoby do skompilowania i debugowania są brakujące w 'BookStoreApi'. Czy dodać je?. Wybierz opcję Tak.

3. Otwórz zintegrowany terminal i uruchom następujące polecenie, aby zainstalować sterownik .NET dla bazy danych MongoDB:

   dotnet add package MongoDB.Driver
   

Dodawanie modelu jednostki

1. Dodaj katalog Models do katalogu głównego projektu.

2. Dodaj klasę Book do katalogu Models przy użyciu następującego kodu:

   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!;
   }
   

   W poprzedniej klasie właściwość Id jest:

   • Wymagane do mapowania obiektu Common Language Runtime (CLR) na kolekcję MongoDB.
   • Dodaj adnotację , [BsonId] aby ustawić tę właściwość jako klucz podstawowy dokumentu.
   • Adnotacje z parametrem [BsonRepresentation(BsonType.ObjectId)] umożliwiają przekazywanie parametru jako typu string zamiast struktury ObjectId . Mongo obsługuje konwersję z string na ObjectId.

   Właściwość BookName jest oznaczona adnotacją z atrybutem [BsonElement] . Wartość atrybutu Name reprezentuje nazwę właściwości w kolekcji MongoDB.

Dodawanie modelu konfiguracji

1. Dodaj następujące wartości konfiguracji bazy danych do :appsettings.json

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

2. Dodaj klasę BookStoreDatabaseSettings do katalogu Models przy użyciu następującego kodu:

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

   Poprzednia BookStoreDatabaseSettings klasa służy do przechowywania appsettings.json wartości właściwości pliku BookStoreDatabase . Nazwy właściwości JSON i C# są nazwane identycznie, aby ułatwić proces mapowania.

3. Dodaj następujący wyróżniony kod do Program.cs:

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

   W poprzednim kodzie instancja konfiguracji, do której wiąże się sekcja pliku appsettings.json, jest zarejestrowana w kontenerze Dependency Injection (DI). Na przykład właściwość obiektu BookStoreDatabaseSettings jest wypełniana właściwością ConnectionString w BookStoreDatabase:ConnectionString.

4. Dodaj następujący kod na górze Program.cs, aby rozwiązać odwołanie BookStoreDatabaseSettings.

   using BookStoreApi.Models;
   

Dodaj usługę operacji CRUD

1. Dodaj katalog Services do katalogu głównego projektu.

2. Dodaj klasę BooksService do katalogu Services za pomocą następującego kodu:

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

   W poprzednim kodzie instancja BookStoreDatabaseSettings jest pobierana z DI za pomocą iniekcji konstruktora. Ta technika zapewnia dostęp do appsettings.json wartości konfiguracji, które zostały dodane w sekcji Dodaj model konfiguracji.

3. Dodaj następujący wyróżniony kod do Program.cs:

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

   W poprzednim kodzie klasa BooksService jest zarejestrowana w DI w celu obsługi wstrzykiwania konstruktora w klasach korzystających. Jednostkowy okres istnienia usługi jest najbardziej odpowiedni, ponieważ BooksService pobiera bezpośrednią zależność od MongoClient. Zgodnie z oficjalnymi wytycznymi ponownego użycia klienta MongoDB, MongoClient należy zarejestrować w DI z czasem życia singletona.

4. Dodaj następujący kod na górze Program.cs, aby rozwiązać odwołanie BooksService.

   using BookStoreApi.Services;
   

Klasa BooksService używa następujących MongoDB.Driver elementów członkowskich do uruchamiania operacji CRUD względem bazy danych:

• MongoClient: pobiera instancję serwera do wykonywania operacji na bazie danych. Konstruktor tej klasy jest udostępniany w parametry połączenia bazy danych MongoDB:

  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: reprezentuje bazę danych Mongo do uruchamiania operacji. W tym samouczku użyto ogólnej metody GetCollection<TDocument>(collection) w interfejsie, aby uzyskać dostęp do danych w określonej kolekcji. Uruchom operacje CRUD względem kolekcji po wywołaniu tej metody. W wywołaniu GetCollection<TDocument>(collection) metody:

  • collection reprezentuje nazwę kolekcji.
  • TDocument reprezentuje typ obiektu CLR przechowywany w kolekcji.

GetCollection<TDocument>(collection) Zwraca obiekt MongoCollection reprezentujący kolekcję. W tym samouczku następujące metody są wywoływane w kolekcji:

• DeleteOneAsync: usuwa pojedynczy dokument zgodny z podanymi kryteriami wyszukiwania.
• Znajdź<TDocument>: Zwraca wszystkie dokumenty w kolekcji, które pasują do podanych kryteriów wyszukiwania.
• InsertOneAsync: wstawia podany obiekt jako nowy dokument w kolekcji.
• ReplaceOneAsync: zastępuje pojedynczy dokument pasujący do podanych kryteriów wyszukiwania podanym obiektem.

Dodawanie kontrolera

Dodaj klasę BooksController do katalogu Controllers z następującym kodem:

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

Poprzedni kontroler internetowego interfejsu API:

• Używa klasy do uruchamiania operacji CRUD BooksService.
• Zawiera metody akcji do obsługi żądań HTTP GET, POST, PUT i DELETE.
• Wywołuje CreatedAtAction w metodzie akcji Create, aby zwrócić odpowiedź HTTP 201. Kod stanu 201 to standardowa odpowiedź metody HTTP POST, która tworzy nowy zasób na serwerze. CreatedAtAction również dodaje nagłówek Location do odpowiedzi. Nagłówek Location wskazuje URI nowo utworzonej książki.

Konfigurowanie opcji serializacji JSON

Istnieją dwa szczegóły dotyczące odpowiedzi JSON zwróconych w sekcji Testowanie internetowego interfejsu API :

• Domyślne formatowanie nazw właściwości w stylu camel case powinno zostać zmienione, aby odpowiadało stylowi Pascal w nazwach właściwości obiektu CLR.
• Właściwość bookName powinna zostać zwrócona jako Name.

Aby spełnić powyższe wymagania, wprowadź następujące zmiany:

1. W Program.cs, dołącz następujący wyróżniony kod do wywołania metody AddControllers.

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

   Po powyższej zmianie nazwy właściwości w serializowanej odpowiedzi JSON interfejsu API sieci Web są zgodne z odpowiednimi nazwami właściwości w typie obiektu CLR. Na przykład właściwość Book klasy Author serializuje się jako Author zamiast author.

2. W Models/Book.cspliku dodaj adnotację do BookName właściwości za pomocą atrybutu [JsonPropertyName] :

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

   Wartość [JsonPropertyName] atrybutu Name reprezentuje nazwę właściwości w serializowanej odpowiedzi JSON internetowego interfejsu API.

3. Dodaj następujący kod na początku Models/Book.cs , aby rozwiązać odwołanie do atrybutu [JsonProperty]:

   using System.Text.Json.Serialization;
   

4. Powtórz kroki zdefiniowane w sekcji Testowanie internetowego interfejsu API . Zwróć uwagę na różnicę w nazwach właściwości JSON.

Przetestuj internetowy interfejs API

Visual Studio

W tym samouczku używamy Endpoints Explorer i plików .http do testowania interfejsu API.

1. Skompiluj i uruchom aplikację.

2. W Eksploratorze punktów końcowych kliknij prawym przyciskiem myszy pierwszy punkt końcowy /api/books, a następnie wybierz pozycję Generuj żądanie.

   Do pliku zostanie dodana następująca BookStoreApi.http zawartość. Jeśli jest to pierwszy raz, gdy zostanie wygenerowane żądanie, plik zostanie utworzony w katalogu głównym projektu.

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

   Numer portu powinien być już ustawiony na port używany przez aplikację, na przykład https://localhost:56874. Jeśli tak nie jest, możesz znaleźć numer portu w oknie danych wyjściowych podczas uruchamiania aplikacji.

3. Wybierz link Wyślij żądanie powyżej nowego GET wiersza żądania.

   Żądanie GET jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź .

4. Ciało odpowiedzi pokazuje wynik JSON zawierający rekordy książek podobne do następujących:

   [
     {
       "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. Aby pobrać pojedynczą książkę, kliknij prawym przyciskiem myszy /api/books/{id}, params (string id) punkt końcowy GET w Eksploratorze punktów końcowych i wybierz polecenie Generuj żądanie.

   Następująca zawartość jest dołączana do BookStoreApi.http pliku:

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

6. Zastąp id zmienną jednym z identyfikatorów zwróconych z wcześniejszego żądania, na przykład:

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

7. Wybierz link Wyślij żądanie powyżej nowego GET wiersza żądania.

   Żądanie GET jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź .

8. Treść odpowiedzi zawiera kod JSON podobny do następującego:

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

9. Aby przetestować punkt końcowy POST, kliknij prawym przyciskiem myszy /api/books punkt końcowy POST i wybierz polecenie Generuj żądanie.

   Do pliku zostanie dodana następująca BookStoreApi.http zawartość:

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

10. Zastąp komentarz książki obiektem książki jako treścią żądania JSON:

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

11. Wybierz link Wyślij żądanie powyżej POST wiersza żądania.

    Żądanie POST jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź . Odpowiedź powinna zawierać nowo utworzoną książkę z przypisanym identyfikatorem.

12. Na koniec, aby usunąć książkę, kliknij prawym przyciskiem myszy /api/books/{id}, params (string id) punkt końcowy DELETE i wybierz polecenie Generuj żądanie.

    Następująca zawartość jest dołączana do BookStoreApi.http pliku:

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

13. Zastąp zmienną id jednym z identyfikatorów zwróconych z wcześniejszego żądania, a następnie kliknij pozycję Wyślij żądanie. Przykład:

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

Visual Studio Code

W tym samouczku do testowania interfejsu API użyto specyfikacji interfejsu OpenAPI (openapi.json) i interfejsu użytkownika struktury Swagger .

1. Zainstaluj interfejs użytkownika programu Swagger, uruchamiając następujące polecenie:

dotnet add package NSwag.AspNetCore

Poprzednie polecenie dodaje pakiet NSwag.AspNetCore, który zawiera narzędzia do generowania dokumentów i interfejsu użytkownika Swagger. Ponieważ nasz projekt wykorzystuje OpenAPI, używamy tylko pakietu NSwag do generowania Swagger UI.

1. Konfigurowanie oprogramowania pośredniczącego Swagger

W Program.csdodaj następujący wyróżniony kod:

var app = builder.Build();

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

Poprzedni kod umożliwia middleware Swagger do obsługi wygenerowanego dokumentu JSON przy użyciu interfejsu Swagger. Program Swagger jest włączony tylko w środowisku projektowym. Włączenie Swagger w środowisku produkcyjnym może ujawniać szczegóły, które mogą być poufne, dotyczące struktury i implementacji API.

Aplikacja używa dokumentu OpenAPI wygenerowanego przez OpenApi, znajdującego się w lokalizacji /openapi/v1.json, do generowania UI. Wyświetl wygenerowaną specyfikację interfejsu OpenAPI dla interfejsu API WeatherForecast, gdy projekt jest uruchomiony, przechodząc do https://localhost:<port>/openapi/v1.json w przeglądarce.

Specyfikacja interfejsu OpenAPI to dokument w formacie JSON, który opisuje strukturę i możliwości interfejsu API, w tym punkty końcowe, formaty żądań/odpowiedzi, parametry i inne. Zasadniczo jest to strategia interfejsu API, która może być używana przez różne narzędzia do zrozumienia interfejsu API i interakcji z nim.

1. Skompiluj i uruchom aplikację.

2. W przeglądarce przejdź do strony https://localhost:<port>/swagger. Narzędzie Swagger udostępnia interfejs użytkownika do testowania wszystkich punktów końcowych interfejsu API na podstawie dokumentu OpenAPI.

3. Rozwiń punkt końcowy GET /api/books i kliknij przycisk Wypróbuj .

4. Kliknij przycisk Wykonaj , aby wysłać żądanie do interfejsu API.

5. Sekcja Treść odpowiedzi zawiera tablicę JSON z książkami podobnymi do następujących:

   [
     {
       "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. Następnie rozwiń endpoint GET /api/books/{id} i kliknij Wypróbuj.

7. Wprowadź jeden z identyfikatorów książki z poprzedniej odpowiedzi w polu id , a następnie kliknij przycisk Wykonaj.

8. W sekcji Treść odpowiedzi zostanie wyświetlony obiekt JSON dla określonej książki. Na przykład wynik identyfikatora 61a6058e6c43f32854e51f52 jest podobny do następującego:

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

9. Aby przetestować tworzenie nowej książki, rozwiń endpoint POST /api/books i kliknij opcję Wypróbuj.

10. Zastąp domyślną treść żądania nowym obiektem książki:

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

11. Kliknij przycisk Wykonaj , aby wysłać żądanie.

12. Odpowiedź powinna mieć kod stanu 201 (Utworzony) i dołączyć nowo utworzoną książkę z przypisanym identyfikatorem w treści odpowiedzi.

13. Na koniec, aby usunąć rekord książki, rozwiń punkt końcowy DELETE /api/books/{id}, kliknij Wypróbuj i wprowadź jeden z identyfikatorów książek z poprzedniej odpowiedzi w polu id. Kliknij przycisk Wykonaj , aby wysłać żądanie.

14. Odpowiedź powinna mieć kod stanu 204 (Brak zawartości), wskazujący, że książka została pomyślnie usunięta.

Dodawanie obsługi uwierzytelniania do internetowego interfejsu API

ASP.NET Core Identity dodaje funkcje logowania interfejsu użytkownika do aplikacji internetowych platformy ASP.NET Core. Aby zabezpieczyć webowe interfejsy API i SPA, użyj jednego z następujących rozwiązań:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C )
• Serwer Duende Identity

Duende Identity Server to struktura OpenID Connect i OAuth 2.0 dla ASP.NET Core. Serwer Duende Identity umożliwia korzystanie z następujących funkcji zabezpieczeń:

• Uwierzytelnianie jako usługa (AaaS)
• Logowanie jednokrotne/wylogowanie w wielu typach aplikacji
• Kontrola dostępu dla interfejsów API
• Brama federacyjna

Ważne

Oprogramowanie Duende może wymagać zapłacenia opłaty licencyjnej za korzystanie z serwera Duende Identity Server w środowisku produkcyjnym. Aby uzyskać więcej informacji, zobacz Migrowanie z platformy ASP.NET Core na platformie .NET 5 do platformy .NET 6.

Aby uzyskać więcej informacji, zobacz dokumentację serwera Duende (witryna internetowa Duende Identity Software).

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Tworzenie internetowych interfejsów API za pomocą platformy ASP.NET Core
• Zwracane typy akcji kontrolera w ASP.NET Core web API
• Tworzenie internetowego interfejsu API przy użyciu platformy ASP.NET Core