この投稿はQWERTYUによって2019年4月12日14:24に最終編集されました。
紹介API開発に asp.net Coreを使った後、APIドキュメントの作成はプログラマーにとっては骨の折れる作業になるでしょうが、ドキュメントは必ず作成されなければならず、ドキュメントのフォーマットに特別な要件がなければ、最終的なドキュメントは開発者の気分に完全に左右されます。 あるいはもっと詳細に、あるいはシンプルに。 では、APIドキュメントを迅速かつ効率的に作成する方法はありますか? 答えはイエスです。Swaggerは最も人気のあるREST APIドキュメント生成ツールの一つです!
なぜSwaggerをREST APIのドキュメント生成ツールとして使うのか- Swaggerは、開発者がAPIを素早く学習・実験できるインタラクティブAPIコンソールを生成できます。
- Swaggerは、さまざまなプラットフォームでの実装のためのクライアントSDKコードを生成できます。
- Swaggerファイルは、さまざまなプラットフォームのコードコメントから自動的に生成できます。
- Swaggerには多くの強力な貢献者がいる強力なコミュニティがあります。
Swaggerを使って asp.net コアでAPIドキュメントを生成するにはどうすればいいですか?- Swashbuckle.AspNetCoreは、Core Web API用のSwaggerドキュメントを生成するオープンソースプロジェクト ASP.NET。
- NSwagは、Swagger UIやReDocをコアWeb APIに統合するための別のオープンソースプロジェクト ASP.NET です。 API用のC#およびTypeScriptクライアントコードを生成する方法を提供します。
以下はSwashbuckle.AspNetCoreの例ですスウォッシュバックルの構成要素とは何でしょうか?- Swashbuckle.AspNetCore.Swagger:SwaggerDocumentオブジェクトをSwaggerオブジェクトモデルおよびJSONエンドポイントのミドルウェアとして公開します。
- Swashbuckle.AspNetCore.SwaggerGen:ルート、コントローラー、モデルから直接SwaggerDocumentオブジェクトを生成するSwaggerジェネレーターです。 しばしばSwaggerエンドポイントミドルウェアと組み合わせてSwagger JSONを自動的に公開します。
- Swashbuckle.AspNetCore.SwaggerUI:Swagger UIツールの組み込み版です。 Swagger JSONを解釈し、Web APIの機能を説明するカスタマイズ可能で豊かな体験を構築します。 一般的な手法のための組み込みテストツールが含まれています。
VS2017でSwashbuckleをどう取り付ける?
最初の方法は、パッケージマネージャーのコンソールウィンドウからインストールすることです
- 他のWindows > >パッケージマネージャーコンソールのビューへ
- TodoApi.csprojファイルを含むディレクトリへ移動してください
- 次のコマンドを実行してください・ インストールパッケージ Swashbuckle.AspNetCore
-
第二の方法:Manage NuGet Packagesのダイアログから:- ソリューションエクスプローラーでプロジェクトを右クリック>NuGetパッケージ管理
- パッケージソースを nuget.org に設定
- 検索ボックスに「Swashbuckle.AspNetCore」と入力してください
- ブラウズタブからSwashbuckle.AspNetCoreパッケージを選択し、「インストール」をクリックします
-
Swaggerミドルウェアの追加と設定まず名前空間を紹介します: Startup.ConfigureServicesメソッドのサービスコレクションにSwaggerジェネレーターを追加します: でStartup.Configure生成されたJSONドキュメントとSwagger UIをミドルウェアで提供できるようにする方法:
アプリを起動してそこに移動してくださいhttps://localhost:<port>/swagger/v1/swagger.json。 エンドポイントを説明するドキュメントはJSON形式で以下のように表示されます。
利用可能https://localhost:<port>/スワガーSwaggerのUIを見つけてください。 以下のようにSwagger UIからAPIドキュメントを閲覧してください。
根を適用するには (http://localhost:<port>/Swagger UIを提供するには、ルートプレフィックスこのプロパティは空文字列に設定されます:
Swaggerの高度な活用(カスタマイズと拡張機能)Swaggerを使ってAPIドキュメントに説明情報を追加しましょう以下の設定操作はAddSwaggerGenメソッドで実行され、著者、ライセンス、説明情報などの情報が追加されます。 ワガーUI表示バージョンの情報は以下の図に示されています: インターフェースメソッドへのコメント追加まずAPIをクリックして、下の図のように展開します。コメントがないのですか?コメントの追加方法は? 下の画像に示すように、ドキュメントコメントを3/で追加します。 その後、プロジェクトを実行してswaggerUIに戻ってコメントが表示されるか確認してください まだ現れなかった、心配しないで、下を見て! XML注釈を有効にするXML注釈を有効にする方法は以下の通りです: - ソリューションエクスプローラーでプロジェクトを右クリックし、「プロパティ」を選択してください
- ビルドタブの出力セクションにあるXMLドキュメントファイルボックスをご覧ください
-
XMLアノテーションを有効にすると、未公開の共通型やメンバーのデバッグ情報が得られます。 例えば、多数の警告メッセージが表示された場合、以下のメッセージは警告コード1591の違反を示しています。
もしOCDで警告を取り消したいとしたらどうしますか? 下の画像のようにキャンセルできます
上記で生成されたxmlドキュメントファイルの経路に注目してください。
手記： 1. Linuxや非Windowsオペレーティングシステムでは、ファイル名とパスは大文字を区別します。 例えば、「SwaggerDemo.xml」ファイルはWindowsでは動作しますが、CentOSでは動作しません。 2. アプリケーションパスを取得するには、AppContext.BaseDirectoryを使用して取得することをお勧めします プロジェクトを再構築して実行し、コメントが表示されるか確認してください 上記の操作からまとめると、Swagger UIは<summary>上記のコメントコードの要素の内部テキストをAPIの大きなコメントとして表示しています! もちろん、コメントの要素を「Get How to」ドキュメントに追加することもできます。 要素<summary>で指定された情報を補完し、より信頼性の高いSwagger UIを提供できます。 <remarks> 要素の内容はテキスト、JSON、またはXMLのいずれかを含みます。 コードは以下の通りです: SwaggerUIを使ってAPIインターフェースをテストしてくださいSwaggerUIを使ってインターフェースをデバッグしてみましょう。小さな例を挙げてみます
- テストが必要なAPIインターフェースをクリックし、パラメータの左右にある「試してみる」ボタンをクリックしてください
- パラメータテキストボックスにパラメータを入力してください。以下の画像のように、パラメータ2を入力してください
- 実行ボタンをクリックすると、下図のように以下のフォーマット済みレスポンスが表示されます
さて、今日のSwaggerを使ってCore WebApiでAPIドキュメントを生成するチュートリアル ASP.NET これで終わりです。 Swaggerを使って ASP.NET CoreでAPIドキュメントを生成する方法を学ぶのが役に立てば幸いです! 概要この記事は、手作業でAPIドキュメントを作成する際の苦痛点から始まり、次に自動的にAPIドキュメントを生成するツールであるSwaggerへとつながります! 次に、わかりやすいテキストと画像を通じて、SwaggerUIを使って ASP.NET コアWebAPIでAPIドキュメントを生成する方法を実演します。 最後に、ASP.NET Coreでのスワガーの高度な使い方を紹介します! Swaggerを ASP.NET Coreで使う役に立てば嬉しいです!
| 
掲載地 2019/04/12 14:14:46
|
|
|
|
