Udostępnij za pośrednictwem


Wprowadzenie do sieciowych grup zabezpieczeń i platformy ASP.NET Core

Przez Christoph Nienaber, Rico Suter i Dave Brock

Wyświetl lub pobierz przykładowy kod (jak pobrać)

NSwag oferuje następujące możliwości:

  • Możliwość korzystania z interfejsu użytkownika struktury Swagger i generatora struktury Swagger.
  • Elastyczne możliwości generowania kodu.

W przypadku sieciowej grupy zabezpieczeń nie potrzebujesz istniejącego interfejsu API — możesz użyć interfejsów API innych firm, które zawierają program Swagger i generują implementację klienta. NSwag pozwala przyspieszyć cykl programowania i łatwo dostosować się do zmian interfejsu API.

Instalacja pakietu

Zainstaluj serwer NSwag, aby:

  • Wygeneruj specyfikację struktury Swagger dla zaimplementowanego internetowego interfejsu API.
  • Udostępniaj interfejs użytkownika struktury Swagger, aby przeglądać i testować internetowy interfejs API.
  • Udostępniaj dokument Redoc, aby dodać dokumentację interfejsu API dla internetowego interfejsu API.

Aby użyć oprogramowania pośredniczącego NSwag ASP.NET Core, zainstaluj pakiet NuGet NSwag.AspNetCore. Ten pakiet zawiera oprogramowanie pośredniczące do generowania i obsługi specyfikacji struktury Swagger, interfejsu użytkownika struktury Swagger (wersja 2 i wersja 3) oraz interfejsu użytkownika redoc. NSwag 14 obsługuje tylko 3 specyfikacji interfejsu użytkownika struktury Swagger.

Aby zainstalować pakiet NuGet NSwag, użyj jednej z następujących metod:

  • W oknie konsoli Menedżer pakietów:

    • Przejdź do pozycji Wyświetl>inne okna> Menedżer pakietów Konsola

    • Przejdź do katalogu, w którym NSwagSample.csproj istnieje plik

    • Wykonaj następujące polecenie:

      Install-Package NSwag.AspNetCore
      
  • W oknie dialogowym Zarządzanie pakietami NuGet:

    • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań> Zarządzanie pakietami NuGet
    • Ustaw źródło pakietu na wartość "nuget.org"
    • Wprowadź ciąg "NSwag.AspNetCore" w polu wyszukiwania
    • Wybierz pakiet "NSwag.AspNetCore" na karcie Przeglądaj , a następnie kliknij przycisk Zainstaluj

Dodawanie i konfigurowanie oprogramowania pośredniczącego struktury Swagger

Dodaj i skonfiguruj program Swagger w aplikacji ASP.NET Core, wykonując następujące kroki:

  • Dodaj generator OpenApi do kolekcji usług w pliku Program.cs:
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();
  • Włącz oprogramowanie pośredniczące do obsługi wygenerowanej specyfikacji openApi, interfejsu użytkownika struktury Swagger i interfejsu użytkownika narzędzia Redoc również w systemie Program.cs:
if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}
  • Uruchomić aplikację. Przejdź do:
    • http://localhost:<port>/swagger aby wyświetlić interfejs użytkownika struktury Swagger.
    • http://localhost:<port>/swagger/v1/swagger.json aby wyświetlić specyfikację struktury Swagger.

Generowanie kodu

Możesz skorzystać z możliwości generowania kodu NSwag, wybierając jedną z następujących opcji:

Generowanie kodu za pomocą aplikacji NSwagStudio

  • Zainstaluj aplikację NSwagStudio, postępując zgodnie z instrukcjami w repozytorium GitHub NSwagStudio. Na stronie wydania NSwag można pobrać wersję narzędzia xcopy, która może zostać uruchomiona bez uprawnień administratora i instalacji.
  • Uruchom aplikację swagger.json NSwagStudio i wprowadź adres URL pliku w polu tekstowym Adres URL specyfikacji struktury Swagger. Na przykład http://localhost:5232/swagger/v1/swagger.json.
  • Kliknij przycisk Utwórz lokalną kopię , aby wygenerować reprezentację formatu JSON specyfikacji struktury Swagger.

Program NSwag Studio importuje specyfikację i eksportuje klienta CSharp.

  • W obszarze Dane wyjściowe kliknij pole wyboru Klient CSharp. W zależności od projektu możesz również wybrać klienta TypeScript lub kontrolera internetowego interfejsu API CSharp. W przypadku wybrania kontrolera internetowego interfejsu API CSharp specyfikacja usługi ponownie kompiluje usługę, służąc jako generowanie odwrotne.
  • Kliknij pozycję Generuj dane wyjściowe , aby utworzyć kompletną implementację klienta języka C# projektu TodoApi.NSwag . Aby wyświetlić wygenerowany kod klienta, kliknij kartę Klient CSharp:
namespace MyNamespace
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
    public partial class TodoClient
    {
    #pragma warning disable 8618 // Set by constructor via BaseUrl property
        private string _baseUrl;
    #pragma warning restore 8618 // Set by constructor via BaseUrl property
        private System.Net.Http.HttpClient _httpClient;
        private static System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(CreateSerializerSettings, true);

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            BaseUrl = "http://localhost:5232";
            _httpClient = httpClient;
        }

        private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
        {
            var settings = new Newtonsoft.Json.JsonSerializerSettings();
            UpdateJsonSerializerSettings(settings);
            return settings;
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set
            {
                _baseUrl = value;
                if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                    _baseUrl += '/';
            }
        }
        // code omitted for brevity

Napiwek

Kod klienta języka C# jest generowany na podstawie wyborów na karcie Ustawienia . Zmodyfikuj ustawienia, aby wykonywać zadania, takie jak domyślna przestrzeń nazw i synchroniczna generacja metody.

  • Skopiuj wygenerowany kod języka C# do pliku w projekcie klienta, który będzie używać interfejsu API.
  • Rozpocznij korzystanie z internetowego interfejsu API:
var todoClient = new TodoClient(new HttpClient());

// Gets all to-dos from the API
var allTodos = await todoClient.GetAsync();

// Create a new TodoItem, and save it via the API.
await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

Dostosowywanie dokumentacji interfejsu API

Interfejs OpenApi udostępnia opcje dokumentowania modelu obiektów w celu ułatwienia użycia internetowego interfejsu API.

Informacje i opis interfejsu API

W Program.csprogramie zaktualizuj informacje AddOpenApiDocument o dokumencie internetowego interfejsu API i dołącz więcej informacji, takich jak autor, licencja i opis. Najpierw zaimportuj NSwag OpenApi przestrzeń nazw, aby używać klas.

using NSwag;

var builder = WebApplication.CreateBuilder(args);

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

W interfejsie użytkownika struktury Swagger są wyświetlane informacje o wersji:

Interfejs użytkownika programu Swagger z informacjami o wersji.

Komentarze XML

Aby włączyć komentarze XML, wykonaj następujące kroki:

  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz pozycję Edit <project_name>.csproj.
  • Ręcznie dodaj wyróżnione wiersze do .csproj pliku:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Włączenie komentarzy XML zapewnia informacje debugowania dla nieudokumentowanych typów publicznych i elementów członkowskich. Nieudokumentowane typy i elementy członkowskie są wskazywane przez komunikat ostrzegawczy. Na przykład następujący komunikat wskazuje naruszenie kodu ostrzeżenia 1591:

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

Aby pominąć ostrzeżenia dla całego projektu, zdefiniuj rozdzielaną średnikami listę kodów ostrzeżeń, które mają być ignorowane w pliku projektu. Dołączanie kodów ostrzegawczych w celu $(NoWarn); zastosowania wartości domyślnych języka C#.

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

Aby pominąć ostrzeżenia tylko dla określonych elementów członkowskich, należy ująć kod w #pragma dyrektywy preprocesora ostrzegawczego . Takie podejście jest przydatne w przypadku kodu, który nie powinien być udostępniany za pośrednictwem dokumentacji interfejsu API. W poniższym przykładzie kod ostrzeżenia CS1591 jest ignorowany dla całej TodoContext klasy. Wymuszanie kodu ostrzegawczego jest przywracane na zamknięciu definicji klasy. Określ wiele kodów ostrzegawczych z rozdzielaną przecinkami listą.

namespace NSwagSample.Models;

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

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

Adnotacje do danych

Oznacz model atrybutami znajdującymi się w przestrzeni nazw, aby pomóc w kierowania składnikami interfejsu System.ComponentModel.DataAnnotations użytkownika struktury Swagger.

[Required] Dodaj atrybut do Name właściwości TodoItem klasy:

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

namespace NSwagSample.Models;

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

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

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

Obecność tego atrybutu zmienia zachowanie interfejsu użytkownika i zmienia bazowy schemat JSON:

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

W miarę wzrostu użycia adnotacji danych w internetowym interfejsie API strony pomocy interfejsu użytkownika i interfejsu API stają się bardziej opisowe i przydatne.

Opisywanie typów odpowiedzi

Deweloperzy korzystający z internetowego interfejsu API są najbardziej zainteresowani zwracanymi typami odpowiedzi i kodami błędów (jeśli nie są standardami). Typy odpowiedzi i kody błędów są oznaczone w komentarzach XML i adnotacjach danych.

Akcja Create zwraca kod stanu HTTP 201 w przypadku powodzenia. Kod stanu HTTP 400 jest zwracany, gdy wysłana treść żądania to null. Bez odpowiedniej dokumentacji w interfejsie użytkownika struktury Swagger użytkownik nie zna tych oczekiwanych wyników. Rozwiąż ten problem, dodając wyróżnione wiersze w poniższym przykładzie:

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

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

Interfejs użytkownika struktury Swagger teraz wyraźnie dokumentuje oczekiwane kody odpowiedzi HTTP (a komentarze XML są również wyświetlane):

Interfejs użytkownika struktury Swagger przedstawiający opis klasy odpowiedzi POST

Konwencje mogą służyć jako alternatywa do jawnego dekorowania poszczególnych akcji za pomocą polecenia [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Używanie konwencji internetowego interfejsu API.

Ponowne dokumenty

Redoc to alternatywa dla interfejsu użytkownika struktury Swagger. Jest ona podobna, ponieważ udostępnia również stronę dokumentacji internetowego interfejsu API przy użyciu specyfikacji interfejsu OpenAPI. Różnica polega na tym, że interfejs użytkownika redoc jest bardziej skoncentrowany na dokumentacji i nie zapewnia interaktywnego interfejsu użytkownika do testowania interfejsu API.

Aby włączyć dokument Redoc, dodaj oprogramowanie pośredniczące do :Program.cs

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI is called only in Development.
    
    // Add ReDoc UI to interact with the document
    // Available at: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Uruchom aplikację i przejdź do http://localhost:<port>/redoc witryny , aby wyświetlić interfejs użytkownika narzędzia Redoc:

Dokumentacja ponownego dokumentu dla przykładowego interfejsu API.

Przez Christoph Nienaber, Rico Suter i Dave Brock

Wyświetl lub pobierz przykładowy kod (jak pobrać)

NSwag oferuje następujące możliwości:

  • Możliwość korzystania z interfejsu użytkownika struktury Swagger i generatora struktury Swagger.
  • Elastyczne możliwości generowania kodu.

W przypadku sieciowej grupy zabezpieczeń nie potrzebujesz istniejącego interfejsu API — możesz użyć interfejsów API innych firm, które zawierają program Swagger i generują implementację klienta. NSwag pozwala przyspieszyć cykl programowania i łatwo dostosować się do zmian interfejsu API.

Rejestrowanie oprogramowania pośredniczącego NSwag

Zarejestruj oprogramowanie pośredniczące NSwag, aby:

  • Wygeneruj specyfikację struktury Swagger dla zaimplementowanego internetowego interfejsu API.
  • Udostępniaj interfejs użytkownika struktury Swagger, aby przeglądać i testować internetowy interfejs API.

Aby użyć oprogramowania pośredniczącego NSwag ASP.NET Core, zainstaluj pakiet NuGet NSwag.AspNetCore. Ten pakiet zawiera oprogramowanie pośredniczące do generowania i obsługi specyfikacji struktury Swagger, interfejsu użytkownika struktury Swagger (wersja 2 i wersja 3) oraz interfejsu użytkownika redoc.

Aby zainstalować pakiet NuGet NSwag, użyj jednej z następujących metod:

  • W oknie konsoli Menedżer pakietów:

    • Przejdź do pozycji Wyświetl>inne okna> Menedżer pakietów Konsola

    • Przejdź do katalogu, w którym TodoApi.csproj istnieje plik

    • Wykonaj następujące polecenie:

      Install-Package NSwag.AspNetCore
      
  • W oknie dialogowym Zarządzanie pakietami NuGet:

    • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań> Zarządzanie pakietami NuGet
    • Ustaw źródło pakietu na wartość "nuget.org"
    • Wprowadź ciąg "NSwag.AspNetCore" w polu wyszukiwania
    • Wybierz pakiet "NSwag.AspNetCore" na karcie Przeglądaj , a następnie kliknij przycisk Zainstaluj

Dodawanie i konfigurowanie oprogramowania pośredniczącego struktury Swagger

Dodaj i skonfiguruj program Swagger w aplikacji ASP.NET Core, wykonując następujące kroki:

  • W metodzie Startup.ConfigureServices zarejestruj wymagane usługi Swagger:
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}
  • W metodzie Startup.Configure włącz oprogramowanie pośredniczące do obsługi wygenerowanej specyfikacji struktury Swagger i interfejsu użytkownika struktury Swagger:
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseOpenApi();
    if (env.IsDevelopment())
    {
        app.UseSwaggerUi3();
    }
    app.UseMvc();
}
  • Uruchomić aplikację. Przejdź do:
    • http://localhost:<port>/swagger aby wyświetlić interfejs użytkownika struktury Swagger.
    • http://localhost:<port>/swagger/v1/swagger.json aby wyświetlić specyfikację struktury Swagger.

Generowanie kodu

Możesz skorzystać z możliwości generowania kodu NSwag, wybierając jedną z następujących opcji:

Generowanie kodu za pomocą aplikacji NSwagStudio

  • Zainstaluj aplikację NSwagStudio, postępując zgodnie z instrukcjami w repozytorium GitHub NSwagStudio. Na stronie wydania NSwag można pobrać wersję xcopy, która może zostać uruchomiona bez uprawnień instalacji i administratora.

  • Uruchom aplikację swagger.json NSwagStudio i wprowadź adres URL pliku w polu tekstowym Adres URL specyfikacji struktury Swagger. Na przykład http://localhost:44354/swagger/v1/swagger.json.

  • Kliknij przycisk Utwórz lokalną kopię , aby wygenerować reprezentację formatu JSON specyfikacji struktury Swagger.

    Tworzenie lokalnej kopii specyfikacji struktury Swagger

  • W obszarze Dane wyjściowe kliknij pole wyboru Klient CSharp. W zależności od projektu możesz również wybrać klienta TypeScript lub kontrolera internetowego interfejsu API CSharp. W przypadku wybrania kontrolera internetowego interfejsu API CSharp specyfikacja usługi ponownie kompiluje usługę, służąc jako generowanie odwrotne.

  • Kliknij pozycję Generuj dane wyjściowe , aby utworzyć kompletną implementację klienta języka C# projektu TodoApi.NSwag . Aby wyświetlić wygenerowany kod klienta, kliknij kartę Klient CSharp:

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

Napiwek

Kod klienta języka C# jest generowany na podstawie wyborów na karcie Ustawienia . Zmodyfikuj ustawienia, aby wykonywać zadania, takie jak domyślna przestrzeń nazw i synchroniczna generacja metody.

  • Skopiuj wygenerowany kod języka C# do pliku w projekcie klienta, który będzie używać interfejsu API.
  • Rozpocznij korzystanie z internetowego interfejsu API:
 var todoClient = new TodoClient();

// Gets all to-dos from the API
 var allTodos = await todoClient.GetAllAsync();

 // Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

Dostosowywanie dokumentacji interfejsu API

Program Swagger udostępnia opcje dokumentowania modelu obiektów w celu ułatwienia użycia internetowego interfejsu API.

Informacje i opis interfejsu API

W metodzie Startup.ConfigureServices akcja konfiguracji przekazana do AddSwaggerDocument metody dodaje informacje, takie jak autor, licencja i opis:

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

W interfejsie użytkownika struktury Swagger są wyświetlane informacje o wersji:

Interfejs użytkownika programu Swagger z informacjami o wersji

Komentarze XML

Aby włączyć komentarze XML, wykonaj następujące kroki:

  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz pozycję Edit <project_name>.csproj.
  • Ręcznie dodaj wyróżnione wiersze do .csproj pliku:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Adnotacje do danych

Ponieważ NSwag używa odbicia, a zalecany typ zwracany dla akcji internetowego interfejsu API to ActionResult<T>, może on wnioskować tylko typ zwracany zdefiniowany przez T. Nie można automatycznie wywnioskować innych możliwych typów zwracanych.

Rozważmy następujący przykład:

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Poprzednia akcja zwraca wartość ActionResult<T>. Wewnątrz akcji zwraca CreatedAtRoutewartość . Ponieważ kontroler ma [ApiController] atrybut, BadRequest odpowiedź jest również możliwa. Aby uzyskać więcej informacji, zobacz Automatyczne odpowiedzi HTTP 400. Użyj adnotacji danych, aby poinformować klientów o kodach stanu HTTP, które ta akcja jest znana do zwrócenia. Oznacz akcję następującymi atrybutami:

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

W ASP.NET Core 2.2 lub nowszym można użyć konwencji zamiast jawnego dekorowania poszczególnych akcji za pomocą polecenia [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Używanie konwencji internetowego interfejsu API.

Generator struktury Swagger może teraz dokładnie opisać tę akcję i wygenerować klientów, którzy wiedzą, co otrzymują podczas wywoływania punktu końcowego. Jako zalecenie oznacz wszystkie akcje za pomocą tych atrybutów.

Aby uzyskać wskazówki dotyczące odpowiedzi HTTP, które powinny zwracać akcje interfejsu API, zobacz RFC 9110: Semantyka HTTP (sekcja 9.3). Definicje metod).