2.2 NetCoreの予防策とエントリの使用よりもNetCore 3.1でSwashbuckle闊歩

文化的背景

Swashbuckleは、3つの主要なコンポーネントがあります。

Swashbuckle.AspNetCore.Swagger

SwaggerDocumentオブジェクトが闊歩し、ミドルウェアJSONエンドポイントのオブジェクトモデルを公開します。

Swashbuckle.AspNetCore.SwaggerGen

直接ルーティングコントローラと発生SwaggerDocumentオブジェクトモデル闊歩発生器から。これは通常、開示された自動闊歩JSON、闊歩中間エンドポイントと組み合わされます。

Swashbuckle.AspNetCore.SwaggerUI

組み込みバージョン闊歩UIツール。それはカスタマイズすることができます豊富な経験を説明Web API関数を構築するために闊歩JSONを説明します。これは、内蔵のテストツールのパブリックメソッドに含まれています。

NetCore 3に取り付けられました

Nugetインストール：Swashbuckle.AspNetCoreバージョン5.0以上を推奨

闊歩は、発電機に加えるStartup.ConfigureServices方法でサービスのセット

NetCore 3.1、の元NetCore2.2 InfoアップグレードされましたOpenApiInfo。

基本的なバージョン

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

アップグレード版

メインプロジェクト生成された地元のチェックを忘れないでください、XMLを生成し、これを強化するために使用

// 注册Swagger生成器，定义一个和多个Swagger文档
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("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);
});

XMLファイル名に一致するウェブAPIプロジェクトを生成するためのリフレクション。パス構築XMLファイルのAppContext.BaseDirectoryプロパティ。XMLドキュメントファイルを使用せずに機能するために、いくつかの闊歩関数（入力パラメータ、またはHTTPメソッド及びレスポンスコードを、例えば、アーキテクチャ各属性）。ほとんどの機能（すなわちメソッドの概要およびパラメータ説明と応答コードの記述）の場合、あなたはXMLファイルを使用する必要があります。

ではStartup.Configure方法、JSON文書と闊歩UIサービスを生成するためのミドルウェアを有効にします

基本的なバージョン

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

アップグレード版

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

    // 要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：
    //c.RoutePrefix = string.Empty;

    // 要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：
    c.RoutePrefix = "doc";
});

カット言葉遣い

インターフェイスは、説明のコメントを追加します

/// <summary>
/// 获取列表信息
/// </summary>
/// <returns></returns>
[HttpGet]
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

コードを表示闊歩UI <summary>テキスト要素内

モデル説明インターフェイスの増加

/// <summary>
/// 获取列表信息
/// </summary>
/// <remarks>
/// 示例请求:
///
///     GET /Get
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <returns></returns>
[HttpGet]
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

意志 要素は、操作ドキュメントのGetメソッドに追加されます。これは、追加することができます

情報が要素に指定され、より信頼性の高い闊歩UIを提供しています。 要素の内容は、テキスト、JSONまたはXMLを含めることができます。

データモデルは、メモを追加します

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

使い方System.ComponentModel.DataAnnotationsヘルプドライブ闊歩UIコンポーネントに名前空間属性タグモデル。ウィル[Required]に属性を追加TodoItemするクラスのNameプロパティ。

コントローラの応答コンテンツタイプを記載します

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

ウィル[Produces("application/json")]APIコントローラにプロパティを追加します。この操作の目的は、コントローラの声明サポートすることでapplication/json、応答コンテンツタイプを。

の種類に応じて述べ制御動作

/// <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(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

ウェブAPI開発者を使用して問題が最も懸念している、特にタイプとエラーコード（標準ではない場合）に応じて、戻ってコンテンツです。これは、応答とコメントのXMLコメントにエラーコードとデータの種類を示します。
成功したリターンHTTP 201ステータスコードの後に操作を作成します。解放要求本体がHTTP 400ステータスコードを返し、NULLです。闊歩UIが適切な文書を提供していない場合、ユーザーは、これらの期待される結果の理解の欠如になります。

カスタムプライベートラベルのUI

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

APIドキュメントのページには、ブランドやテーマを表している必要があります。あなたは、静的なファイルを提供するためのリソースを追加し、これらのファイルをホストするフォルダ構造を構築する必要があるとして、Swashbuckleは、コンポーネントをマークします。

闊歩UI GitHubのリポジトリからdistのフォルダの内容を取得します。このフォルダには、必要な資産闊歩UIページが含まれています。
wwwrootに/闊歩/ UIフォルダを作成し、それに内容distのフォルダをコピーします。
ページタイトルをカスタマイズするために、wwwrootに/闊歩/ UIでのcustom.cssファイルを作成するには、次のCSSを使用します

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

他のCSSファイルへの参照した後に、index.htmlのファイルのcustom.css内の「UI」フォルダを引用：

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

参考リソース

SwashbuckleとASP.NETコアスターター