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とは

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を生成してみた

開発環境はこんな感じ

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 =&gt; {
            c.SwaggerEndpoint(&quot;/swagger/v1/swagger.json&quot;, &quot;RemainderAPI v1&quot;);
        });
    }

[/csharp]

このままでも動くことは動きますが,APIメソッドの概要等が抜けてしまうので,下記変更をします.

  1. Webプロジェクトを右クリック -> オプション -> コンパイラにある XML ドキュメントを生成するにチェックしてディレクトリを選択
  2. Startup.csConfigureServices に下記コードを追加

[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 =&gt; { 
            c.SwaggerDoc(&quot;v1&quot;, new Info{ Title = &quot;RemainderAPI&quot;, Version = &quot;v1&quot;});
            var xmlPath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, &quot;Remainder.xml&quot;);
            c.IncludeXmlComments(xmlPath);
        });
    }

[/csharp]

ちなみにXMLドキュメントを生成するにチェックを入れるとXMLコメントが付いていないメソッド・クラスは全てWarning扱いになります。 まぁビルドは通るので無視しても構いませんがうざいなぁと思う人は空のXMLコメントでもつけておきましょう(笑)

こんな感じで一通りつくってデバッグ実行でアクセスするとこんな感じになると思います

swagger-ui

ちなみにAPIメソッドのタブを開くとこんな感じ

swagger-ui-open

この画面から試しにAPIを叩くこともできます.便利.

あと,これはSwaggerの設定を追加する必要がありますが,APIにJwtなどの認証設定している場合はメニューバーにある Authorize にtokenをセットすれば認証のテストなども可能になっています. (もちろんこれらの情報もSwagger-specに記載されます)

Swagger Editorで中身を見る

自動生成したswagger.jsonをダウンロードして,Swagger Editor に読み込ませる。

SwaggerEditor

左にOpenAPIのyaml,右にSwagger-UIが表示されます.

編集もできますが,サーバ側で自動生成したものを編集することはまず無いと思われますw まぁエラーチェックくらいには使えるかな程度でしょう。

Swagger-specからクライアントコードを生成する

Swagger EditorのGenerate Client からクライアント側で使用する言語を選択してダウンロード. いろいろ選べますが今回はとりあえずrubyで生成しています.

Swagger-codegen-lib

クライアントコードと一緒にmarkdownのドキュメントもついてきます.

一応APIのコードもちょっとみて見ると,

swageer-codegen-ruby

おお、なんかそれらしいコードが生成されてる.

という感じで,swagger-codegenでクライアントサイドで使う言語に合わせてコードを自動生成 -> クライアントアプリに組み込む といった感じの使い方ができます。

Swagger-specからサーバサイドコードを生成する

こっちは実例が少ないので割愛。 簡単に言うと,定義書からサーバサイドアプリの雛形を作る,感じでしょうか?


まとめ

WebAPIを作る際に、ドキュメントも併せて必要となることが多いと思われますが,Swaggerを使えばその辺りが自動化できるほか,クライアントサイドのコードも自動で作ってくれる(しかもアプリ開発の言語に合わせて)ので,サーバサイド,フロントエンド,それぞれ分業しやすくなるのではないでしょうか? また,Swagger-UIを生成できるライブラリがあれば,サーバサイド・クライアントサイドともに開発言語の自由が効きやすいのではないかと思います.

あと、Swagger-specを作ってからサーバサイドコードを生成するやり方もあるようですが,Swagger-spec自体書きやすいかと言われるとそうでは無いので,個人的にはそういった使い方はしないかな。

明日はmecaotaくんですでした


参考資料