Začínáme se NS zamykací ASP.NET Core

OdEnenber,Riko Sutera Dave Brock

NSplach nabízí následující možnosti:

• Možnost využívat uživatelské rozhraní Swagger a generátor Swagger.
• Flexibilní možnosti generování kódu.

S NSggerem nepotřebujete existující rozhraní API, můžete použít rozhraní API třetích stran, která zahrnují — Swagger a generují implementaci klienta. NSwag umožňuje urychlit vývojový cyklus a snadno se přizpůsobit změnám rozhraní API.

Registrace middlewaru NSwag

Zaregistrujte middleware NSwag pro:

• Vygenerování specifikace Swaggeru pro implementované webové rozhraní API
• Procházejte a testujte webové rozhraní API pomocí Swagger UI.

Pokud chcete použít middleware ASP.NET Core NS windows, nainstalujte balíček NuGet NSwag.AspNetCore. Tento balíček obsahuje middleware pro vygenerování a obsluhu specifikace Swaggeru, swagger UI (v2 a v3) a uživatelské rozhraní ReDoc.

K instalaci balíčku NS NuGet použijte jeden z následujících přístupů:

dotnet add TodoApi.csproj package NSwag.AspNetCore

Přidání a konfigurace middlewaru Swagger

Pomocí následujících kroků přidejte a nakonfigurujte Swagger ASP.NET Core vaší aplikaci:

• V Startup.ConfigureServices metodě zaregistrujte požadované služby Swagger:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}

• V Startup.Configure metodě povolte middleware pro obsluhu vygenerované specifikace Swaggeru a uživatelského rozhraní Swaggeru:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}

• Spustit aplikaci Přejděte na:
  • http://localhost:<port>/swagger pro zobrazení uživatelského rozhraní Swaggeru.
  • http://localhost:<port>/swagger/v1/swagger.json zobrazíte specifikaci Swaggeru.

Generování kódu

Výběrem jedné z následujících možností můžete využít výhod možností generování kódu NS za vás:

• NSstudio:Desktopová Windows pro generování klientského kódu rozhraní API v jazyce C# nebo TypeScript.
• NS windows.CodeGeneration.CSharp nebo NS zaklíčování.CodeGeneration.TypeScript NuGet pro generování kódu v rámci projektu.
• Příkaz NS windows z příkazového řádku.
• Balíček NS zachyt MSBuild NuGet.
• Připojená služba OpenAPI (Swagger):Připojená služba Visual Studio pro generování klientského kódu rozhraní API v jazyce C# nebo TypeScript. Také generuje kontrolery jazyka C# pro služby OpenAPI pomocí služby NS windows.

Generování kódu pomocí NSmessageStudia

• Nainstalujte NSstudio podle pokynů v úložišti NSstudio GitHub . Na stránce vydání nástroje NS windows si můžete stáhnout verzi xcopy, kterou můžete spustit bez oprávnění správce a instalace.

• Spusťte NSstudio a do textovéhoswagger.js Url specifikace Swaggeru zadejte adresu URLswagger.jssouboru. Příklad: http://localhost:44354/swagger/v1/swagger.json.

• Kliknutím na tlačítko Create local Copy (Vytvořit místní kopii) vygenerování reprezentace specifikace Swagger ve formátu JSON.

  

• V oblasti Výstupy zaškrtněte políčko Klient CSharp. V závislosti na projektu můžete také zvolit TypeScript Client nebo CSharp Web API Controller. Pokud vyberete kontroler webového rozhraní API CSharp, specifikace služby znovu sestaví službu, která slouží jako zpětná generace.

• Kliknutím na Vygenerovat výstupy vytvořte úplnou klientskou implementaci projektu TodoApi.NS pro jazyk C#. Pokud chcete zobrazit vygenerovaný kód klienta, klikněte na kartu 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

• Zkopírujte vygenerovaný kód jazyka C# do souboru v klientském projektu, který bude rozhraní API využívat.
• Začněte používat webové rozhraní 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);

Přizpůsobení dokumentace k rozhraní API

Swagger nabízí možnosti pro dokumentování objektového modelu, aby se usnadnila spotřeba webového rozhraní API.

Informace a popis rozhraní API

V metodě přidá konfigurační akce předaná metodě informace, jako je Startup.ConfigureServices autor, licence a AddSwaggerDocument popis:

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

Swagger UI zobrazí informace o verzi:

Komentáře XML

Pokud chcete povolit komentáře XML, proveďte následující kroky:

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

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

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

<PropertyGroup>
  <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Datové poznámky

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

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

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

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

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

Generátor Swagger teď může přesně popsat tuto akci a vygenerovaní klienti vědí, co dostanou při volání koncového bodu. Jako doporučení označte všechny akce pomocí těchto atributů.

Pokyny k odpovědím HTTP, které by měly vaše akce rozhraní API vracet, najdete ve specifikaci RFC 7231.