Asp.Netcore WebApi Swaggerを使用したヘルプページの生成
最近私たちのチームはずっと行われています.Netcoreの転換、web開発は前後端に分離する技術アーキテクチャに進化し、私たちのバックグラウンドは主にaspを採用した.Netcore webapiが開発を行い、デバッグのたびにフロントエンドとのコミュニケーションに効率が悪いという問題があり、マイクロソフトaspを一度見ています.Netcore公式ドキュメントの時、swaggerといういいものを見つけました.そして実際のプロジェクトにこの技術を導入した.私たちの開発者が自分で書いたapiをテストする過程は大幅に簡略化され、フロントエンドの人も私たちが提供したswagger help pagesに基づいて自分でいくつかのフロントエンドコードのテストを行うことができ、前後の開発効率を大幅に向上させた.次に私は自分の本当のオンラインプロジェクトを持って、aspでどのように説明します.Netcore webapiにswaggerを導入します.(Microsoftの公式文書も参照:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger)
一、swagger Nugetパッケージの導入
wepapiプロジェクトの依存項目を右クリックし、管理Nugetパッケージをクリックします.以下の図です.
開いているNuGetパッケージ管理インタフェースで、「Swashbuckle」と入力します.AspNetCoreは現在、パッケージのバージョンが1.0.0なので、インストールをクリックします.
インストールが完了したら、プロジェクトのStartupが必要です.csファイルで構成します.
二、Swaggerの配置
スタートを切るcsファイル、ConfigureServicesメソッドで、次のコードを追加します.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "TwBusManagement ",
Description = "RESTful API for TwBusManagement",
TermsOfService = "None",
Contact = new Contact { Name = "Alvin_Su", Email = "[email protected]", Url = "" }
}); //Set the comments path for the swagger json and ui.
var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "twbusapi.xml");
c.IncludeXmlComments(xmlPath); // c.OperationFilter(); // httpHeader
}); 上段コードの最後の3行は、apiがドキュメントxmlの生成アドレスとファイル名を記述し、プロジェクトのプロパティで構成する必要があることに注意してください.次の図を示します.
また、上図では、警告の表示を禁止し、1591コードを追加することで、クラス名にコメントが書かれていないアラーム情報をフィルタリングすることができます.
最後にConfigureメソッドでは、次のようなコードを追加する必要があります.以下のコードはappに追加する必要があります.UseMvc()の前:
// 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", "TwBusManagement API V1");
c.ShowRequestHeaders();
});以上の構成が完了すると、Swaggerで生成されたヘルプページを使用できます.プロジェクトを実行すると、ブラウザアドレスに接尾辞/swaggerを付けると、ヘルプページにジャンプできます.
もちろん、開発者はプロジェクトを開発する過程で、毎回手動でアドレスを入力してヘルプページにジャンプするのは面倒ではありません.次の図に示すように、visual studioを使用してジャンプできます.
開けてjsonファイルは、webapiプロジェクトの起動パスをswaggerに設定します.これにより、実行項目をデバッグするたびにswaggerヘルプページに自動的にジャンプします.
三、Swaggerのいくつかの高級な使い方
Swaggerは非常に強力で、ヘルプページ情報だけでなくapiのデバッグもできます.これにより、postmanなどのサードパーティツールを使用してwebapiのデバッグを行う必要がなくなります.swaggerは構成されており、権限認証情報などのhttpヘッダ情報を入力することもできます.以下、具体的な構成について説明します.
まず、名前空間を導入する必要があるIOperationFilterインタフェースを継承するクラスHttpHeaderOperationを新規作成する必要があります.AspNetCore.SwaggerGen,実装インタフェースメソッドApplyコードは以下の通りである.
public class HttpHeaderOperation : IOperationFilter
{ public void Apply(Operation operation, OperationFilterContext context)
{ if (operation.Parameters == null)
{
operation.Parameters = new List();
} var actionAttrs = context.ApiDescription.ActionAttributes(); var isAuthorized= actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute)); if (isAuthorized == false) // action ， { var controllerAttrs= context.ApiDescription.ControllerAttributes();
isAuthorized= controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
} var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute)); if (isAuthorized && isAllowAnonymous == false)
{
operation.Parameters.Add(new NonBodyParameter()
{
Name = "Authorization", // Authorization
In = "header",
Type = "string",
Required = false
});
}
}
} そしてスタータープでcsのConfigureServicesメソッドでは、前のAddSwaggerGenコードセグメントを見つけ、最後に次のコードを追加します.
c.OperationFilter() services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "TwBusManagement ",
Description = "RESTful API for TwBusManagement",
TermsOfService = "None",
Contact = new Contact { Name = "Alvin_Su", Email = "[email protected]", Url = "" }
}); //Set the comments path for the swagger json and ui.
var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "twbusapi.xml");
c.IncludeXmlComments(xmlPath);
c.OperationFilter(); // httpHeader
}); これにより、webapiプロジェクトを許可すると、Authorizationヘッダパラメータを入力できます.次の図を示します.