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

Shayne Boyer および Scott AddieBy Shayne Boyer and Scott Addie

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

Swashbuckle には 3 つの主要なコンポーネントがあります。There are three main components to Swashbuckle:

  • Swashbuckle.AspNetCore.Swagger: SwaggerDocument オブジェクトを JSON エンドポイントとして公開するための Swagger オブジェクト モデルとミドルウェア。Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.

  • Swashbuckle.AspNetCore.SwaggerGen: ルート、コントローラー、モデルから直接 SwaggerDocument オブジェクトを構築する Swagger ジェネレーター。Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models. 通常、Swagger エンドポイント ミドルウェアと組み合わせて Swagger JSON を自動的に公開します。It's typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: Swagger UI ツールの埋め込みバージョン。Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. Swagger JSON を解釈して、Web API の機能を説明するカスタマイズ可能な機能豊富なエクスペリエンスを構築します。It interprets Swagger JSON to build a rich, customizable experience for describing the Web API functionality. これには、パブリック メソッド用の組み込みのテスト ハーネスが含まれます。It includes built-in test harnesses for the public methods.

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

Swashbuckle は、次の方法で追加できます。Swashbuckle 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 Swashbuckle.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"
    • 検索ボックスに「Swashbuckle.AspNetCore」と入力します。Enter "Swashbuckle.AspNetCore" in the search box
    • [参照] タブから "Swashbuckle.AspNetCore"パッケージを選択して、[インストール] をクリックします。Select the "Swashbuckle.AspNetCore" package from the Browse tab and click Install

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

Startup.ConfigureServices メソッドで Swagger ジェネレーターをサービス コレクションに追加します。Add the Swagger generator to the services collection in the Startup.ConfigureServices method:

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

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });
}

次の名前空間をインポートし、Info クラスを使用します。Import the following namespace to use the Info class:

using Swashbuckle.AspNetCore.Swagger;

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

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}

前述の UseSwaggerUI メソッド呼び出しにより、静的ファイル ミドルウェアが有効になります。The preceding UseSwaggerUI method call enables the Static Files Middleware. .NET Framework または .NET Core 1.x を対象とする場合は、Microsoft.AspNetCore.StaticFiles NuGet パッケージをプロジェクトに追加します。If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.

アプリを起動し、http://localhost:<port>/swagger/v1/swagger.json に移動します。Launch the app, and navigate to http://localhost:<port>/swagger/v1/swagger.json. Swagger 仕様 (swagger.json) に基づき、エンドポイントについて説明するドキュメントが生成され、表示されます。The generated document describing the endpoints appears as shown in Swagger specification (swagger.json).

Swagger UI は http://localhost:<port>/swagger にあります。The Swagger UI can be found at http://localhost:<port>/swagger. Swagger UI から API を探し、他のプログラムに組み込みます。Explore the API via Swagger UI and incorporate it in other programs.

ヒント

アプリのルート (http://localhost:<port>/) で Swagger UI にサービスを提供するには、RoutePrefix プロパティを空の文字列に設定します。To serve the Swagger UI at the app's root (http://localhost:<port>/), set the RoutePrefix property to an empty string:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

カスタマイズと拡張Customize and extend

Swagger は、テーマに合わせてオブジェクト モデルを文書化して、UI をカスタマイズするオプションを提供します。Swagger provides options for documenting the object model and customizing the UI to match your theme.

API 情報と説明API info and description

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

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        },
        License = new License
        {
            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 can be 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.

XML コメントを有効にすると、ドキュメントに未記載のパブリック型とメンバーのデバッグ情報を提供することができます。Enabling XML comments provides debug information for undocumented public types and members. 文書化されない型とメンバーは警告メッセージで示されます。Undocumented types and members are indicated by the warning message. たとえば、次のメッセージは警告コード 1591 の違反を示します。For example, the following message indicates a violation of warning code 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

プロジェクト全体で警告を非表示にするには、プロジェクト ファイルで無視する警告コードの一覧をセミコロン区切りで定義します。To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file. 警告コードを $(NoWarn); に追加すると、C# の既定値が適用されます。Appending the warning codes to $(NoWarn); applies the C# default values too.

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

特定のメンバーに向けた警告のみを非表示にするには、コードを #pragma warning プリプロセッサ ディレクティブで囲みます。To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives. この方法は、API ドキュメント経由で公開すべきではないコードの場合に役立ちます。次の例では、警告コード CS1591 が Program クラス全体で無視されます。This approach is useful for code that shouldn't be exposed via the API docs. In the following example, warning code CS1591 is ignored for the entire Program class. 警告コードの強制は、クラス定義の終了時に復元されます。Enforcement of the warning code is restored at the close of the class definition. コンマ区切りのリストで複数の警告コードを指定します。Specify multiple warning codes with a comma-delimited list.

namespace TodoApi
{
#pragma warning disable CS1591
    public class Program
    {
        public static void Main(string[] args) =>
            BuildWebHost(args).Run();

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
#pragma warning restore CS1591
}

生成された XML ファイルを使用するように Swagger を構成します。Configure Swagger to use the generated XML file. Linux または Windows 以外のオペレーティング システムでは、ファイル名やパスで大文字小文字が区別されます。For Linux or non-Windows operating systems, file names and paths can be case-sensitive. たとえば、TodoApi.XML ファイルは Windows では有効ですが、CentOS では無効です。For example, a TodoApi.XML file is valid on Windows but not CentOS.

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

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = "https://twitter.com/spboyer"
            },
            License = new License
            {
                Name = "Use under LICX",
                Url = "https://example.com/license"
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt => 
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = "https://twitter.com/spboyer"
            },
            License = new License
            {
                Name = "Use under LICX",
                Url = "https://example.com/license"
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = "https://twitter.com/spboyer"
            },
            License = new License
            {
                Name = "Use under LICX",
                Url = "https://example.com/license"
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

前述のコードでは、Reflection を使用し、Web API プロジェクトの名前に一致する XML ファイル名が構築されます。In the preceding code, Reflection is used to build an XML file name matching that of the Web API project. AppContext.BaseDirectory プロパティは、XML ファイルのパス構築に使用されます。The AppContext.BaseDirectory property is used to construct a path to the XML file.

アクションにトリプル スラッシュのコメントを追加すると、セクション ヘッダーに説明が追加され、Swagger UI が向上します。Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Delete アクションの上に <summary> 要素を追加します。Add a <summary> element above the Delete action:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);

    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();

    return NoContent();
}

Swagger UI には、前述のコードの <summary> 要素の内部テキストが表示されます。The Swagger UI displays the inner text of the preceding code's <summary> element:

DELETE メソッドの XML コメント 'Deletes a specific TodoItem.' を

UI は、生成された JSON スキーマによって決まります。The UI is driven by the generated JSON schema:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "operationId": "ApiTodoByIdDelete",
    "consumes": [],
    "produces": [],
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "type": "integer",
            "format": "int64"
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
}

<remarks> 要素を Create アクション メソッドのドキュメントに追加します。Add a <remarks> element to the Create action method documentation. これは、<summary> 要素で指定された情報を補足し、Swagger UI をより堅牢にします。It supplements information specified in the <summary> element and provides a more robust Swagger UI. <remarks> 要素の内容は、テキスト、JSON、または XML で構成されます。The <remarks> element content can consist of text, JSON, or XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
[ProducesResponseType(400)]
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);
}
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

追加コメントで UI が向上している点にご注目ください。Notice the UI enhancements with these additional comments:

追加のコメントが表示された Swagger UI

データの注釈Data annotations

System.ComponentModel.DataAnnotations 名前空間にある属性をモデルに追加し、Swagger UI コンポーネントの向上に役立てます。Decorate the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components.

[Required] 属性を TodoItem クラスの Name プロパティに追加します。Add the [Required] attribute to the Name property of the TodoItem class:

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

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

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

この属性の有無は、UI 動作を変更し、基になる JSON スキーマを変更します。The presence of this attribute changes the UI behavior and alters the underlying JSON schema:

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

API コントローラーに [Produces("application/json")] 属性を追加します。Add the [Produces("application/json")] attribute to the API controller. その目的は、コントローラーのアクションが application/json の応答コンテンツ タイプをサポートすることを宣言することです。Its purpose is to declare that the controller's actions support a response content type of application/json:

[Produces("application/json")]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;
[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

[応答コンテンツ タイプ] ドロップダウンがコント ローラーの GET 操作の既定値としてこのコンテンツ タイプを選択します。The Response Content Type drop-down selects this content type as the default for the controller's GET actions:

既定の応答のコンテンツ タイプを持つ Swagger UI

Web API のデータの注釈の使用量が多いほど、UI と API のヘルプ ページはわかりやすく便利になります。As the usage of data annotations in the Web API increases, the UI and API help pages become more descriptive and useful.

応答の種類の説明Describe response types

開発者は、何が返されるかを、具体的には、応答の種類とエラー コード (標準以外の場合) を最も考慮します。Consuming developers are most concerned with what's returned—specifically response types and error codes (if not standard). 応答の種類とエラー コードは、XML コメントとデータ注釈に示されます。The response types and error codes are denoted in the XML comments and data annotations.

Create アクションでは、成功すると HTTP 201 状態コードが返されます。The Create action returns an HTTP 201 status code on success. HTTP 400 状態コードは、投稿された要求本文が null のときに返されます。An HTTP 400 status code is returned when the posted request body is null. Swagger UI に適切なドキュメントがないと、利用者にはこれらの予期される結果の知識がありません。Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. その問題を解決するために、次の例では強調表示された行を追加しています。Fix that problem by adding the highlighted lines in the following example:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
[ProducesResponseType(400)]
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);
}
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

Swagger UI は、予期される HTTP 応答コードを明確に記述するようになりました。The Swagger UI now clearly documents the expected HTTP response codes:

ステータスコードの POST 応答クラスの説明 'Returns the newly created Todo item' and '400 - If the item is null' および応答メッセージの下に理由を示す Swagger UI

UI をカスタマイズするCustomize the UI

ストック UI は機能も見栄えも優れています。The stock UI is both functional and presentable. しかしながら、API ドキュメント ページでブランドやテーマを表す必要があります。However, API documentation pages should represent your brand or theme. Swashbuckle コンポーネントをブランド化するには、静的ファイルにサービスを提供するリソースを追加し、それらのファイルをホストするフォルダー構造を構築する必要があります。Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.

.NET Framework または .NET Core 1.x を対象としている場合、プロジェクトに Microsoft.AspNetCore.StaticFiles NuGet パッケージを追加します。If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project:

<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />

.NET Core 2.x を対象とし、メタパッケージを使用している場合、前述の NuGet パッケージが既にインストールされています。The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.

静的ファイル ミドルウェアを有効にします。Enable the static files middleware:

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

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}

Swagger UI GitHub リポジトリから dist フォルダーの内容を取得します。Acquire the contents of the dist folder from the Swagger UI GitHub repository. このフォルダーには、Swagger UI ページに必要なアセットが含まれています。This folder contains the necessary assets for the Swagger UI page.

wwwroot/swagger/ui フォルダーを作成し、それに dist フォルダーのコンテンツをコピーします。Create a wwwroot/swagger/ui folder, and copy into it the contents of the dist folder.

wwwroot/swagger/uicustom.css ファイルを作成し、次の CSS でページ ヘッダーをカスタマイズします。Create a custom.css file, in wwwroot/swagger/ui, with the following CSS to customize the page header:

.swagger-ui .topbar {
    background-color: #000;
    border-bottom: 3px solid #547f00;
}

他に CSS ファイルがあればその後で index.html ファイルの custom.css を参照します。Reference custom.css in the index.html file, after any other CSS files:

<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css">
<link rel="stylesheet" type="text/css" href="custom.css">

http://localhost:<port>/swagger/ui/index.htmlindex.html ページを参照します。Browse to the index.html page at http://localhost:<port>/swagger/ui/index.html. ヘッダーのテキスト ボックスに「http://localhost:<port>/swagger/v1/swagger.json」を入力し、[探索] ボタンをクリックします。Enter http://localhost:<port>/swagger/v1/swagger.json in the header's textbox, and click the Explore button. 結果のページは次のようになります。The resulting page looks as follows:

カスタム ヘッダーのタイトルを含む Swagger UI

このページでできることはたくさんあります。There's much more you can do with the page. Swagger UI GitHub リポジトリで UI リソースの完全な機能を参照してください。See the full capabilities for the UI resources at the Swagger UI GitHub repository.