NSwag と ASP.NET Core の概要Get started with NSwag and ASP.NET Core

作成者: Christoph Nienaber および Rico SuterBy Christoph Nienaber and Rico Suter

NSwag と共に ASP.NET Core ミドルウェアを使用するには、NSwag.AspNetCore NuGet パッケージが必要です。Using NSwag with ASP.NET Core middleware requires the NSwag.AspNetCore NuGet package. このパッケージは、Swagger ジェネレーター、Swagger UI (v2 と v3)、ReDoc UI で構成されています。The package consists of a Swagger generator, Swagger UI (v2 and v3), and ReDoc UI.

NSwag のコード生成機能を利用することを強くお勧めします。It's highly recommended to make use of NSwag's code generation capabilities. コード生成に次のいずれかのオプションを選択します。Choose one of the following options for code generation:

フィーチャーFeatures

NSwag を使用する主な理由は、Swagger UI と Swagger ジェネレーターを導入できることのみならず、柔軟なコード生成機能を利用できることにあります。The main reason to use NSwag is the ability to not only introduce the Swagger UI and Swagger generator, but to make use of the flexible code generation capabilities. 既存の API は必要ありません—Swagger が組み込まれているサードパーティ製の API を利用し、NSwag にクライアント実装を生成させることができます。You don't need an existing API—you can use third-party APIs that incorporate Swagger and let NSwag generate a client implementation. いずれの方法でも、開発周期が早まり、API 変更に合わせた調整が簡単になります。Either way, the development cycle is expedited and you can more easily adapt to API changes.

パッケージ インストールPackage installation

NSwag NuGet パッケージは、次の方法で追加できます。The NSwag NuGet package can be added with the following approaches:

  • [パッケージ マネージャー コンソール] ウィンドウから:From the Package Manager Console window:

    • [ビュー] > [Other Windows] (その他の Windows) > [パッケージ マネージャー コンソール] に移動します。Go to View > Other Windows > Package Manager Console

    • TodoApi.csproj ファイルが存在するディレクトリに移動します。Navigate to the directory in which the TodoApi.csproj file exists

    • 次のコマンドを実行します。Execute the following command:

      Install-Package NSwag.AspNetCore
      
  • [NuGet パッケージの管理] ダイアログ ボックスから:From the Manage NuGet Packages dialog:

    • [ソリューション エクスプローラー] > [NuGet パッケージの管理] でプロジェクトを右クリックします。Right-click the project in Solution Explorer > Manage NuGet Packages
    • パッケージ ソースを "nuget.org" に設定します。Set the Package source to "nuget.org"
    • 検索ボックスに「NSwag.AspNetCore」と入力します。Enter "NSwag.AspNetCore" in the search box
    • [参照] タブから "NSwag.AspNetCore" パッケージを選択して、[インストール] をクリックします。Select the "NSwag.AspNetCore" package from the Browse tab and click Install

Swagger ミドルウェアを追加して構成するAdd and configure Swagger middleware

Startup クラスで次の名前空間をインポートします。Import the following namespaces in the Startup class:

using NJsonSchema;
using NSwag.AspNetCore;
using System.Reflection;

Startup.Configure メソッドで、生成された Swagger 仕様と SwaggerUI 対応のミドルウェアを有効にします。In the Startup.Configure method, enable the middleware for serving the generated Swagger specification and the Swagger UI:

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

    // Enable the Swagger UI middleware and the Swagger generator
    app.UseSwaggerUi(typeof(Startup).GetTypeInfo().Assembly, settings =>
    {
        settings.GeneratorSettings.DefaultPropertyNameHandling = 
            PropertyNameHandling.CamelCase;
    });

    app.UseMvc();
}

アプリを起動します。Launch the app. http://localhost:<port>/swagger に移動し、Swagger UI を表示します。Navigate to http://localhost:<port>/swagger to view the Swagger UI. http://localhost:<port>/swagger/v1/swagger.json に移動し、Swagger 仕様を表示します。Navigate to http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

コード生成Code generation

NSwagStudio からVia NSwagStudio

  • 公式 GitHub repository リポジトリから NSwagStudio をインストールします。Install NSwagStudio from the official GitHub repository.
  • NSwagStudio を起動します。Launch NSwagStudio. [Swagger Specification URL] (Swagger 仕様 URL) テキストボックスに swagger.json ファイルの URL を入力し、[Create local Copy] (ローカル コピーの作成) ボタンをクリックします。Enter the swagger.json file URL in the Swagger Specification URL textbox, and click the Create local Copy button.
  • [CSharp Client] (CSharp クライアント) クライアント出力の種類を選択します。Select the CSharp Client client output type. 他の選択肢には、[TypeScript Client](TypeScript クライアント)[CSharp Web API Controller](CSharp Web API コントローラー) があります。Other options include TypeScript Client and CSharp Web API Controller. Web API コントローラーは基本的に逆生成です。Using a Web API Controller is basically a reverse generation. サービスの仕様を利用してサービスを再構築します。It uses a specification of a service to rebuild the service.
  • [Generate Outputs] (出力の生成) ボタンをクリックします。Click the Generate Outputs button. TodoApi.NSwag プロジェクトの完全な C# クライアントの実装が作成されます。A complete C# client implementation of the TodoApi.NSwag project is produced. [出力] セクションの [CSharp Client] (CSharp クライアント) タブをクリックし、生成されたクライアント コードを表示します。Click the CSharp Client tab of the Outputs section to see the generated client code:
//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v11.17.3.0 (NJsonSchema v9.10.46.0 (Newtonsoft.Json v9.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable // Disable all warnings

    [System.CodeDom.Compiler.GeneratedCode("NSwag",
        "11.17.3.0 (NJsonSchema v9.10.46.0 (Newtonsoft.Json v9.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "http://localhost:50499";
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient()
        {
            _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

ヒント

C# クライアント コードは、[CSharp Client] (CSharp クライアント) タブの [設定] タブに定義された設定に基づき生成されます。この設定を変更して、既定の名前空間の名前変更や同期メソッドの生成などのタスクを実行します。The C# client code is generated based on settings defined in the Settings tab of the CSharp Client tab. Modify the settings to perform tasks such as default namespace renaming and synchronous method generation.

  • 生成された C# コードは、クライアント プロジェクトのファイルに入れます (例: Xamarin.Forms アプリ)。Copy the generated C# code into a file in a client project (for example, a Xamarin.Forms app).
  • Web API の使用を開始します。Start consuming the web API:
var todoClient = new TodoClient();

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

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

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

注意

ベース URL または HTTP クライアントを API クライアントに挿入できます。You can inject a base URL and/or a HTTP client into the API client. ベスト プラクティスは常に HttpClient を再利用することです。The best practice is to always reuse the HttpClient.

クライアント コードを生成するその他の方法Other ways to generate client code

自分のワークフローにより適した、他の方法でクライアント コードを生成できます。You can generate the client code in other ways, more suited to your workflow:

カスタマイズCustomize

Swagger には、Web API の消費を容易にする、オブジェクト モデルをドキュメント化するオプションがあります。Swagger provides options for documenting the object model to ease consumption of the web API.

API 情報と説明API info and description

Startup.Configureメソッドでは、UseSwagger メソッドに渡された構成アクションによって、作成者、ライセンス、説明などの情報が追加されます。In the Startup.Configure method, a configuration action passed to the UseSwagger method adds information such as the author, license, and description:

// Register the Swagger generator
app.UseSwagger(typeof(Startup).Assembly, settings =>
{
    settings.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.SwaggerContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.SwaggerLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Swagger UI には、バージョンの情報が表示されます。The Swagger UI displays the version's information:

バージョン情報を含む Swagger UI

XML コメントXML comments

XML コメントは次の方法で有効になります。XML comments are enabled with the following approaches:

  • ソリューション エクスプローラーでプロジェクトを右クリックし、[<project_name>.csproj の編集] を選択します。Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • 強調表示された行を手動で .csproj ファイルに追加します。Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • ソリューション エクスプローラーで、プロジェクトを右クリックし、[プロパティ] を選択します。Right-click the project in Solution Explorer and select Properties
  • [ビルド] タブの [出力] セクションの下にある [XML ドキュメント ファイル] チェック ボックスをオンにします。Check the XML documentation file box under the Output section of the Build tab

データの注釈Data annotations

NSwag では、Reflection が使用されます。Web API アクションに推奨される戻り値の型は IActionResult です。NSwag uses Reflection, and the recommended return type for web API actions is IActionResult. 結果的に、NSwag では、アクションの内容とそれで返されるものを推論できません。Consequently, NSwag can't infer what your action is doing and what it returns. 次に例を示します。Consider the following example:

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

先行するアクションによって IActionResult が返されますが、このアクションの内部では CreatedAtRoute または BadRequest を返しています。The preceding action returns IActionResult, but inside the action it's returning either CreatedAtRoute or BadRequest. データ注釈は、このアクションによって返される既知の HTTP 応答コードをクライアントに通知します。Data annotations are used to tell clients which HTTP status codes this action is known to return. アクションに次の属性を追加します。Decorate the action with the following attributes:

[ProducesResponseType(typeof(TodoItem), 201)]   // Created
[ProducesResponseType(400)]                     // BadRequest

NSwag では、Reflection が使用されます。Web API アクションに推奨される戻り値の型は ActionResult<T> です。NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>. その結果、NSwag では T によって定義された戻り値のみ推論できます。Consequently, NSwag can only infer the return type defined by T. アクションのその他の可能な戻り値は推論できません。Other possible return types in the action cannot be inferred. 次に例を示します。Consider the following example:

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

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

先行するアクションによって ActionResult<T> が返されますが、このアクションの内部では CreatedAtRoute を返しています。The preceding action returns ActionResult<T>, but inside the action it's returning either CreatedAtRoute. コントローラーは、[ApiController] 属性で修飾されるため、応答として BadRequest も可能です。Since the controller is decorated with the [ApiController] attribute, a BadRequest response is possible too. 詳細については、「自動的な HTTP 400 応答」を参照してください。See Automatic HTTP 400 responses for more info. データ注釈は、このアクションによって返される既知の HTTP 応答コードをクライアントに通知します。Data annotations are used to tell clients which HTTP status codes this action is known to return. アクションに次の属性を追加します。Decorate the action with the following attributes:

[ProducesResponseType(201)]     // Created
[ProducesResponseType(400)]     // BadRequest

Swagger ジェネレーターでは、このアクションを正確に表現できるようになりました。生成されたクライアントでは、エンドポイントの呼び出し時に受け取るものが認識されます。The Swagger generator can now accurately describe this action, and generated clients know what they receive when calling the endpoint. すべてのアクションにこれらの属性を追加することを強くお勧めします。Decorating all actions with these attributes is highly recommended. API アクションで返される HTTP 応答のガイドラインについては、RFC 7231 仕様をご覧ください。For guidelines on what HTTP responses your API actions should return, see the RFC 7231 specification.