.NETコア3.0_webapiプロジェクトが闊歩ヘルプページを使用するためのインタフェースを提供します

　　はじめに：私たちはあなたにも例が必要になることがあり、使用への呼び出しを容易にするために、インターフェイスはアドレス、パラメータと説明指定する必要があり、インタフェースの多くを開発しました。したがって、このオープンソースプロジェクト闊歩、それは解決策の良いセットを提供してくれました。

　　このブログの参考資料：

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

　　闊歩/ OpenAPIのは何ですか？

闊歩は記述するための言語に依存しない仕様です RESTに APIを。闊歩は、プロジェクトに寄贈された OpenAPIの計画、今ではオープンAPIと呼ばれています、。これらの2人の名前が交換可能に使用されるが、OpenAPIのが好ましいです。これは、直接アクセスの実装（ソースコード、ネットワーク・アクセス、文書化）せずに、コンピュータが機能し、人事サービスを理解することができます。目標の一つは、関連付け解除サービスを接続するために必要な労力を最小限に抑えることです。もう一つの目標は、正確な記録にサービスを提供するために必要な時間を短縮することです。（説明は、マイクロソフト公式ドキュメントを参照してください。https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.0）

　　WEBAPIはすぐにプロジェクトの闊歩のサポートを追加します。

　　1 -パッケージ参照を追加：Swashbuckle.AspNetCore -Versionを。5.0 0-RC4（現在プレビュー版に属し、あなたは我々はプレビュー版を見ることができる前にチェックする必要がありますバージョン）

　 2 -追加および設定闊歩ミドルウェア：

使用してMicrosoft.OpenApi.Modelsを。


公共 のボイドConfigureServices（IServiceCollectionサービス）
{
    // 登録闊歩ジェネレータ、1つの以上闊歩文書を定義
            services.AddSwaggerGen（C =>
            {
                c.SwaggerDoc（" V1 "、新 OpenApiInfo {タイトル= " マイAPI "、バージョン= " V1 " }）;

                //は、文書ファイルが含ま 
                c.IncludeXmlComments（Path.Combine（AppContext.BaseDirectory、$ " {。typeof演算（スタートアップ）.Assembly.GetName（）名} .xmlファイル"）、真の）;
            }）;

    services.AddControllers（）;
}

　　ここでは、プロジェクトのXMLファイルへの参照がプロジェクトファイル名のルートディレクトリにデフォルトのxmlファイルで有効になって追加する必要があり、ファイル生成プロジェクトのxml構成は次のとおりです。

　　互換性リリースバージョンについては、我々は、出力パスを設定した名前の空、xmlの変化である：プロジェクト名の.xml

　　3 - Startup.Configure アプローチは、ミドルウェアは、JSON文書と闊歩UIの生成のためのサービスを提供して有効にします。

公共の 無効設定（IApplicationBuilderアプリ）
{
    // JSONエンドポイントとして生成され威張っを提供するミドルウェアを有効にします。
    app.UseSwagger（）;

    // 闊歩-UI（HTML、JS、CSSなど）を提供するためのミドルウェアを有効にし、
     // 闊歩JSONエンドポイントを指定します。
    app.UseSwaggerUI（C =>
    {
        c.SwaggerEndpoint（" /swagger/v1/swagger.json "、" マイAPI V1 " ）;
    }）;

    app.UseStaticFiles（）;
    app.UseRouting（）;
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

　　4-结束，查看效果：

　　启动应用，并导航到： http://localhost:<port>/swagger/v1/swagger.json。生成的描述终结点的文档显示在 Swagger 规范 (swagger.json) 中。

　　可在 http://localhost:<port>/swagger 找到 Swagger UI。通过 Swagger UI 浏览 API

　　5-走过的坑1：官网文档前半部分并没有让添加xml文件的代码。后面有涉及，不过还是感觉有点乱，本博客已加上！

　　走过的坑2：常见异常：Ambiguous HTTP method for action - PaymentAccountAPI.Controllers.PayAccountController.GetTransactions (PaymentAccountAPI). Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0

　　该异常是因为控制器方法，缺少方法类型的标记，[HttpGet]、[HttpPost],如下图：

　　参考解决方案文档：Ambiguous HTTP method Actions require an explicit HttpMethod binding for Swagger 2.0

　　走过的坑3：缺少xml项目文件异常_500错误：项目部署到IIS后，不会自动把xml文件带过去，需要我们收到复制过去，在运行查看效果。

　　把项目xml文件放入后，再试（需要重启IIS项目），效果正常：

.NETコア3.0_webapiプロジェクトが闊歩ヘルプページを使用するためのインタフェースを提供します

おすすめ