SwashbuckleでASP.NET Core WebAPIのSwagger-specを生成してみた
この記事はFUN Advent Calender 2017 16日目の記事です 投稿予定日より少し過ぎてしまいましたが,書きます
誰
雨龍(@prices_over)です.卒業して2年と8ヶ月が経過しました.
都内でMS技術寄りのエンジニアをしています. ついこの前はIE8と戦っていました.
Azureを使ったクラウドソリューションを扱った仕事してます.
昨年はこんな記事書いてました.今年も書かせていただきます. SICPについていろいろ書く
本題
最近仕事でも触れる機会が増えてきたのでSwaggerの話でも. C#的な話を書いたことなかったのと.NET Core触ったこと無いなと思ってとりあえずAPIサーバでも作って見るかー,ってノリで作ったら案外ネタになりそうだなと思ったので.
Swaggerとは
公式では, Open API Specificationを作るためのAPI開発ツールのフレームワーク、といってます. 簡単に言うとRESTful APIのドキュメントを生成してそこからAPI開発者向けコードが作れるなどそういったツール群ですね.
ちなみにOpenAPI Specificationは, Open API InitiativeというRESTful APIドキュメントを標準化しようとする団体がそれを記述するためのフォーマットで,Swaggerをベースにしています.
Swagger Specificationという仕様が先にあって,それをOpen API Initiativeがそれを採択した,という感じでしょうか(話がややこしい…
Swaggerでできること
Swaggerには各種こんなツールが用意されています. - Swagger Editor: OpenAPIの仕様書を編集可能なエディタ. - Swagger UI: Webページ上で見れるAPIドキュメント.各APIメソッドも叩けるようになっている - Swagger Codegen: OpenAPI仕様書から APIクライアントコード・サーバサイドコードが生成できる
中でも注目すべきなのはSwagger Codegenでしょう. SwaggerのAPI定義書(Swagger-spec)を使えばわざわざ自分でクライアントサイドで叩くコードを書かなくて済みます.
Swagger-specの作り方
Swagger Editorでゴリゴリ書いていく…,なんてめんどくさいことはしたくないですよね? 各言語・フレームワーク用向けに作られたSwagger UI生成用のパッケージを使って自動生成があるので,基本的にそれを使うのが主流と思われます. 今回はC#(ASP.NET Core WebAPI)向けの生成パッケージ, Swashbuckleを使っていきます.
ASP.NET Core WebAPIでSwagger-specを生成してみた
開発環境はこんな感じ
- 言語: C#
- フレームワーク: ASP.NET Core WebAPI
- ライブラリ: Swashbuckle
- 開発ツール: Visual Studio for Mac
APIを作成
まずはざっくりAPIを作るところから。
SwaggerUI生成できるところまでいってからスクショ撮ったのでSwagger関連のアノテーションが付いてますが無視してくださいw
ここで重要なのがメソッド・クラスについてるXMLコメント。 このコメントがSwagger-specに反映されるので書くようにしましょう。
Swashbuckleを使ってSwagger UIを生成
Swashbuckle.Coreのパッケージを追加して、 Startup.cs
を編集。
[csharp] /// <summary> /// This method gets called by the runtime. Use this method to configure the HTTP request pipeline. /// </summary> /// <returns>The configure.</returns> /// <param name="app">App.</param> /// <param name="env">Env.</param> public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); }
app.UseMvc();
// Add
app.UseSwagger();
app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "RemainderAPI v1");
});
}
[/csharp]
このままでも動くことは動きますが,APIメソッドの概要等が抜けてしまうので,下記変更をします.
- Webプロジェクトを右クリック -> オプション -> コンパイラにある
XML ドキュメントを生成する
にチェックしてディレクトリを選択 Startup.cs
のConfigureServices
に下記コードを追加
[csharp] /// <summary> /// This method gets called by the runtime. Use this method to add services to the container. /// </summary> /// <param name="services">Services.</param> public void ConfigureServices(IServiceCollection services) {
services.AddMvc();
// Add
services.AddSwaggerGen(c => {
c.SwaggerDoc("v1", new Info{ Title = "RemainderAPI", Version = "v1"});
var xmlPath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "Remainder.xml");
c.IncludeXmlComments(xmlPath);
});
}
[/csharp]
ちなみにXMLドキュメントを生成するにチェックを入れるとXMLコメントが付いていないメソッド・クラスは全てWarning扱いになります。 まぁビルドは通るので無視しても構いませんがうざいなぁと思う人は空のXMLコメントでもつけておきましょう(笑)
こんな感じで一通りつくってデバッグ実行でアクセスするとこんな感じになると思います
ちなみにAPIメソッドのタブを開くとこんな感じ
この画面から試しにAPIを叩くこともできます.便利.
あと,これはSwaggerの設定を追加する必要がありますが,APIにJwtなどの認証設定している場合はメニューバーにある Authorize
にtokenをセットすれば認証のテストなども可能になっています.
(もちろんこれらの情報もSwagger-specに記載されます)
Swagger Editorで中身を見る
自動生成したswagger.jsonをダウンロードして,Swagger Editor に読み込ませる。
左にOpenAPIのyaml,右にSwagger-UIが表示されます.
編集もできますが,サーバ側で自動生成したものを編集することはまず無いと思われますw まぁエラーチェックくらいには使えるかな程度でしょう。
Swagger-specからクライアントコードを生成する
Swagger EditorのGenerate Client
からクライアント側で使用する言語を選択してダウンロード.
いろいろ選べますが今回はとりあえずrubyで生成しています.
クライアントコードと一緒にmarkdownのドキュメントもついてきます.
一応APIのコードもちょっとみて見ると,
おお、なんかそれらしいコードが生成されてる.
という感じで,swagger-codegenでクライアントサイドで使う言語に合わせてコードを自動生成 -> クライアントアプリに組み込む といった感じの使い方ができます。
Swagger-specからサーバサイドコードを生成する
こっちは実例が少ないので割愛。 簡単に言うと,定義書からサーバサイドアプリの雛形を作る,感じでしょうか?
まとめ
WebAPIを作る際に、ドキュメントも併せて必要となることが多いと思われますが,Swaggerを使えばその辺りが自動化できるほか,クライアントサイドのコードも自動で作ってくれる(しかもアプリ開発の言語に合わせて)ので,サーバサイド,フロントエンド,それぞれ分業しやすくなるのではないでしょうか? また,Swagger-UIを生成できるライブラリがあれば,サーバサイド・クライアントサイドともに開発言語の自由が効きやすいのではないかと思います.
あと、Swagger-specを作ってからサーバサイドコードを生成するやり方もあるようですが,Swagger-spec自体書きやすいかと言われるとそうでは無いので,個人的にはそういった使い方はしないかな。
明日はmecaotaくんですでした