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

作成者: Christoph NienaberRico SuterDave BrockBy Christoph Nienaber, Rico Suter, and Dave Brock

NSwag には次の機能があります。NSwag offers the following capabilities:

  • Swagger UI と Swagger Generator を利用できます。The ability to utilize the Swagger UI and Swagger generator.
  • 柔軟なコード生成が可能です。Flexible code generation capabilities.

NSwag では、既存の API は必要ありません—Swagger が組み込まれているサードパーティ製の API を利用し、クライアント実装を生成することができます。With NSwag, you don't need an existing API—you can use third-party APIs that incorporate Swagger and generate a client implementation. NSwag を使用すれば、開発サイクルを短縮でき、API の変更にも容易に対応できます。NSwag allows you to expedite the development cycle and easily adapt to API changes.

NSwag ミドルウェアの登録Register the NSwag middleware

NSwag ミドルウェアの登録でできること:Register the NSwag middleware to:

  • 実装済みの Web API に対して Swagger 仕様を生成します。Generate the Swagger specification for the implemented web API.
  • Web API を参照し、テストするサービスを Swagger UI に提供します。Serve the Swagger UI to browse and test the web API.

NSwag ASP.NET Core ミドルウェアを使用するには、NSwag.AspNetCore NuGet パッケージをインストールします。To use the NSwag ASP.NET Core middleware, install the NSwag.AspNetCore NuGet package. このパッケージには、Swagger 仕様、Swagger UI (v2 と v3)、ReDoc UI を生成し、それらにサービスを提供するミドルウェアが含まれています。This package contains the middleware to generate and serve the Swagger specification, Swagger UI (v2 and v3), and ReDoc UI.

次のいずれかの方法で NSwag NuGet パッケージをインストールします。Use one of the following approaches to install the NSwag NuGet package:

  • [パッケージ マネージャー コンソール] ウィンドウから: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

ASP.NET Core アプリに Swagger を追加して構成します。それには、次の手順を Startup クラスで実行します。Add and configure Swagger in your ASP.NET Core app by performing the following steps in the Startup class:

  • 次の名前空間をインポートします。Import the following namespaces:
using NJsonSchema;
using NSwag.AspNetCore;
  • ConfigureServices メソッドで、必須の Swagger サービスを登録します。In the ConfigureServices method, register the required Swagger services:
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt => 
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}
  • Configure メソッドで、生成された Swagger 仕様と SwaggerUI 対応のミドルウェアを有効にします。In the Configure method, enable the middleware for serving the generated Swagger specification and the Swagger UI:
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

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

    app.UseMvc();
}
  • アプリを起動します。Launch the app. 次に移動します。Navigate to:
    • http://localhost:<port>/swagger (Swagger UI が表示されます)。http://localhost:<port>/swagger to view the Swagger UI.
    • http://localhost:<port>/swagger/v1/swagger.json (Swagger 仕様が表示されます)。http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

コード生成Code generation

次のオプションのいずれかを選択することで、NSwag のコード生成機能を活用できます。You can take advantage of NSwag's code generation capabilities by choosing one of the following options:

NSwagStudio を使用したコード生成Generate code with NSwagStudio

  • NSwagStudio GitHub リポジトリの手順に従って、NSwagStudio をインストールします。Install NSwagStudio by following the instructions at the NSwagStudio GitHub repository.

  • NSwagStudio を起動し、 [Swagger Specification URL](Swagger 仕様 URL) テキスト ボックスに swagger.json ファイルの URL を入力します。Launch NSwagStudio and enter the swagger.json file URL in the Swagger Specification URL text box. たとえば、 http://localhost:44354/swagger/v1/swagger.json です。For example, http://localhost:44354/swagger/v1/swagger.json.

  • [Create local Copy](ローカル コピーの作成) をクリックして、Swagger 仕様の JSON 表現を生成します。Click the Create local Copy button to generate a JSON representation of your Swagger specification.

    Swagger 仕様のローカル コピーの作成

  • [Outputs](出力) 領域で、 [CSharp Client](CSharp クライアント) チェック ボックスをオンにします。In the Outputs area, click the CSharp Client check box. ご自身のプロジェクトに応じて、 [TypeScript Client](TypeScript クライアント) または [CSharp Web API Controller](CSharp Web API コントローラー) を選択することもできます。Depending on your project, you can also choose TypeScript Client or CSharp Web API Controller. [CSharp Web API Controller](CSharp Web API コントローラー) を選択した場合は、逆方向の生成が行われ、サービスの仕様からサービスが再構築されます。If you select CSharp Web API Controller, a service specification rebuilds the service, serving as a reverse generation.

  • [Generate Outputs](出力の生成) をクリックすると、TodoApi.NSwag プロジェクトの完全な C# クライアントの実装が作成されます。Click Generate Outputs to produce a complete C# client implementation of the TodoApi.NSwag project. 生成されたクライアント コードを表示するには、 [CSharp Client](CSharp クライアント) タブをクリックします。To see the generated client code, click the CSharp Client tab:

//----------------------
// <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

ヒント

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

  • 生成された C# コードを、API を消費するクライアント プロジェクト内のファイルにコピーします。Copy the generated C# code into a file in the client project that will consume the API.
  • 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 via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

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

API ドキュメントのカスタマイズCustomize API documentation

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

API 情報と説明API info and description

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

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.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 コメントを有効にするには、次の手順を実行します。To enable XML comments, perform the following steps:

  • ソリューション エクスプローラーでプロジェクトを右クリックし、 [<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 です。そのため、アクションの内容や戻り値の型を推測することはできません。Because NSwag uses Reflection, and the recommended return type for web API actions is IActionResult, it 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 状態コードをクライアントに通知します。Use data annotations 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> です。そのため、T によって定義される戻り値の型のみを推測できます。Because NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>, it can only infer the return type defined by T. 考えられる他の戻り値の型を自動的に推測することはできません。You can't automatically infer other possible return types.

次に例を示します。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> を返します。The preceding action returns ActionResult<T>. アクションの内部では、CreatedAtRoute を返します。Inside the action, it's returning CreatedAtRoute. コントローラーは、[ApiController] 属性で修飾されるため、応答として BadRequest も可能です。Since the controller is decorated with the [ApiController] attribute, a BadRequest response is possible, too. 詳細については、「自動的な HTTP 400 応答」を参照してください。For more information, see Automatic HTTP 400 responses. データ注釈を使用して、このアクションによって返される既知の HTTP 状態コードをクライアントに通知します。Use data annotations 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

ASP.NET Core 2.2 以降では、明示的に個別のアクションを [ProducesResponseType] で修飾する代わりに、規約を使用できます。In ASP.NET Core 2.2 or later, you can use conventions instead of explicitly decorating individual actions with [ProducesResponseType]. 詳細については、「Web API 規約を使用する」を参照してください。For more information, see Web API 規約を使用する.

Swagger ジェネレーターでは、このアクションを正確に表現できるようになりました。生成されたクライアントでは、エンドポイントの呼び出し時に受け取るものが認識されます。The Swagger generator can now accurately describe this action, and generated clients know what they receive when calling the endpoint. すべてのアクションをこれらの属性で修飾することをお勧めします。As a recommendation, decorate all actions with these attributes.

API アクションで返される HTTP 応答のガイドラインについては、RFC 7231 仕様をご覧ください。For guidelines on what HTTP responses your API actions should return, see the RFC 7231 specification.