簡単な紹介
このチュートリアルでは使用していますWHY-WHAT-HOWゴールドリングを考えて書き込み、黄金のルールは、から円を強調することですなぜなぜに、学ぶためにわざわざWHATそして、何かを学ぶどのように方法を学ぶことを。ファジーから学習モードをクリアします。みんなの時間は、私たちがどのような方法によって達成され、その後、私たちは、この目的を達成するために検討し、実現することができる目標の種類を完了し、作業が以前行って理由を知りたい、貴重です。
何もしないよりはまし、障害発生時から学ぶ、いくつかのことを試してみてください。 - マーク。祚KEBO
なぜ私が学ばなければなりませんか？
開発者は、デバッグAPIインターフェースとAPIドキュメントを生成することは非常に困難なことです。私たちは忙しいですが、また、インタフェースのNパラメータのシステムを記述し、状態に戻り、そのようなポストマンなどのサードパーティ製のツールを使用するAPIの正しさをテストするためのフロントエンド開発者インタフェース文書を書かなければなりませんでした。で闊歩出産後、物理的な作業が最終的に大幅に改善されてきた、我々は自動的に美しいインタラクティブなAPIドキュメントを構築することができないだけで、あなたも直接APIインターフェイスをデバッグ正しことができます。闊歩の最新バージョンはようにオープンなAPIの仕様およびJWTトークン不正アクセスのための完全なサポートされているとしています。
何を学ぶことができますか？
- 絶妙なAPIインターフェイスのドキュメントを使用して生成さ闊歩
- 闊歩を使ってJWT認証インターフェイスのデバッグ
- モデルの観点から説明された様々なライブラリを使用して生成さ闊歩
方法は？
闊歩オープンソースプロジェクト住所：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
.NETのコアプロジェクトの作成
まず、.NETのコア3.0のWeb APIプロジェクト、オープンNuget Installation Managerを作成するの左下隅確認する表示のプレビューリリースパッケージを、Swashbuckle.AspNetCoreを検索し、バージョン5.0.0-RC4は、ポイントを追加する注意を払うことを選択し、.NETのコア3.0理由新たにすぐに孵化し、そのうちの多くは、現在のライブラリのプレビューをサポートしている、ここで私は5.0.0-RC4通常の使用を選択し、5.0.0-βが与えられている選択しました。
XML記述を生成する設定
添加が完了した後、数秒待ってから、我々は左だけで作成したAPIプロジェクト、右>のプロパティ（マックレーンと呼ばれるオプション）を選択し、確認したXML文書を生成し、これが闊歩使用されるように生成された情報を記述するために使用されます。
闊歩の設定を開始
その後、我々はオープンStartup.csの中で、闊歩のいくつかの必要な設定を構成するには、ファイルをConfigureServicesの私たちが闊歩構成に関する追加の方法：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Crypto Exchange",
Description = "基于.NET Core 3.0 的区块链数字货币交易所",
Contact = new OpenApiContact
{
Name = "Microfisher",
Email = "[email protected]",
Url = new Uri("http://cnblogs.com/microfisher"),
},
});
// 加载程序集的xml描述文档
var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
var xmlFile = System.AppDomain.CurrentDomain.FriendlyName+ ".xml";
var xmlPath = Path.Combine(baseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
})パラメータは、闊歩インターフェース上に表示される情報のいくつかの単純なもの、私たちはダブルスラッシュのような多くの学生は、MacおよびLinuxでスプライスし、Path.Combineを使用しての習慣を結ぶのパスにここに注意を払う必要があり、それが受け入れられているので、間違って行く可能性がありますオープンソース技術、.NETのコア・バーを開発するためにMacやLinuxを使用してみてください。私たちは、その後、設定方法に次のコードを追加します。
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Crypto Exchange");
// 访问Swagger的路由后缀
c.RoutePrefix = "swagger";
});プレビューマイナー成功
この時点まで、闊歩の私たちの最も基本的な構成は、あなたがアクセスする入力/闊歩サフィックスを空にする必要がない場合は、RoutePrefix闊歩アクセスルートである、完了です。今、私たちは、プロジェクト、HTTPSでの私のローカルサイトを開始するF5を見て：// localhostを：5000、に非常に直接アクセスします。https：// localhostを：以下に示すように5000 /闊歩は、私は、このインターフェイスに行ってきました、醜い良いことそれは絶妙な？そして、不安にならない、我々はゆっくりとチューニング：
JWT認可APIドキュメントを有効にします
現在では、多くのサイトはすぐにサイトを確認する一般的な方法になったそのシンプル、効率的、分散型優位のアカウントの認証および承認システムとしてJWT（JSONのWEBトークン）、JWTを使用します。ここでは、もし興味があるなら、私はJWTの長所と用途を紹介する長い記事を書くことができ、あまりにも多くの導入を行いません。我々はまだ開いている、闊歩JWT許可および認証を追加していくStartup.csの、ファイル上の変更ConfigureServicesにコード方式を：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Crypto Exchange",
Description = "基于.NET Core 3.0 的区块链数字货币交易所",
Contact = new OpenApiContact
{
Name = "Microfisher",
Email = "[email protected]",
Url = new Uri("http://cnblogs.com/microfisher"),
},
});
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
{
Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
BearerFormat = "JWT",
Scheme = "Bearer"
});
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference {
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] { }
}
});
var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml";
var xmlPath = Path.Combine(baseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});プレビューの許可の設定
そして、あなたが右側にもう一つのでしょう、プロジェクトを開始承認 JWTトークンのポイント私たちの情報の後に開くように設定することができます緑のロックボタンを、形式は次のとおりです。トークンにベアラに注意してください、あなたのトークン文字列をベアラ間にスペースがあります。あなたが任意のAPIインターフェイスを要求したときにトークンを設定した後、闊歩は自動的にヘッダートークン要求に出荷されます。
RESTfulなインターフェースを作成します。
私たちは、上記の構成の闊歩を達成した、と今、私たちは、コントローラのデフォルトの世代を削除する必要がありWeatherForecastControllerとビューモデルWeatherForecast、新しいAccountControllerとモデルの複数のビューは、闊歩を説明して文書をインターフェースに戻りましょう。
//[Authorize]
[Produces("application/json")]
[Route("v1/[controller]")]
[ApiController]
public class AccountController : ControllerBase
{
/// <summary>
/// 创建信息
/// </summary>
/// <param name="createViewModel">参数</param>
/// <returns>状态</returns>
[HttpPost]
public StatusViewModel Post([FromBody]CreateViewModel createViewModel)
{
return new StatusViewModel { };
}
/// <summary>
/// 删除信息
/// </summary>
/// <param name="deleteViewModel">参数</param>
/// <returns></returns>
[HttpDelete]
public StatusViewModel Delete([FromQuery]DeleteViewModel deleteViewModel)
{
return new StatusViewModel { };
}
/// <summary>
/// 查询信息
/// </summary>
/// <param name="queryViewModel">参数</param>
/// <returns></returns>
[HttpGet]
public StatusViewModel Get([FromQuery]QueryViewModel queryViewModel)
{
return new StatusViewModel { };
}
/// <summary>
/// 修改信息
/// </summary>
/// <param name="updateViewModel">参数</param>
/// <returns></returns>
[HttpPut]
public StatusViewModel Put([FromQuery]UpdateViewModel updateViewModel)
{
return new StatusViewModel { };
}
}いくつかのビューモデルを作成します。
次のようにして、いくつかの新しいモデルのお好みのスタイルのビューを押した後///各フィールドの概要を追加します。
public class UpdateViewModel
{
/// <summary>
/// ID
/// </summary>
public long Id { get; set; }
/// <summary>
/// 账号
/// </summary>
public long Account { get; set; }
/// <summary>
/// 密码
/// </summary>
public long Password { get; set; }
}試験の最終結果
最後に、私たちはAPIインターフェイスを立ち上げ、その結果を見て、あなたは私たちがモデルを一目で理解するために、フロントエンドの開発者に闊歩が示されている表示するメモを書くことがわかります、インターフェイスの入力パラメータのいくつかは、あなたが実行に関するポイントを見ることができます戻り値の：
JWT（ベアラ123456789）が自由に私を設定されている場合、既に認証情報が含まれている私たちのリクエストヘッダを見て、あなたがライン上でフロントエンドのデバッグトークンを交換しましょう。
