くうと徒然なるままに

ゆるふわ を志向している なごやかです。

ASP.NET Core web API 2.0 で良さげな API 仕様書を Swagger 使って自動錬成する

前書き

API 仕様書作るのつらい

複数人で共同開発をしていて、APIの仕様を伝えなければいけない時がやってきます。

そんな時に Excel に書き込んで共有していてはいろいろつらそうなので簡単にAPIの仕様や使い方を共有できるツールの Swagger というものが存在します。

qiita.com

Swagger を心込めてお手製するのつらい

さて、 Swagger を使ってドキュメント等を作成していきましょう!

という流れになっても Swagger でドキュメントを製作するためには、 YAML ファイル or Json ファイルを編集する必要があります。 しかし、私は怠惰です。 いちいち Json ファイルを編集するのもいやだし、APIの仕様変更に合わせて書き換えるのも嫌です。

だから私は、API仕様書を自動生成する

本題

さて、本題に入っていきましょう

環境

今回使用した環境は以下の通りとなっています。

実際に編集していく

ASP.NET Core web API 2.0 な環境でプロジェクトを作成してください。

f:id:kuxumarin:20170928085201p:plain

Nuget から必要なパッケージをインストールしていく

Nuget パッケージで 検索して入れてください。

Swashbuckle.AspNetCore

f:id:kuxumarin:20170928085537p:plain

コーディング!

Startup.cs を編集していきます。

ConfigureServices 関数の中に以下のものを追加していきます。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1"
        , new Info()
        {
            Title = "API仕様書",
            Version = "v1",
            Description = "概要",
            Contact = new Contact() { Email = "fumiya.kume@homail.com", Name = "kuxu", Url = "Twitter.com/fumiya_kume" }
        });
    c.SwaggerDoc("v2"
        , new Info()
        {
            Title = "API仕様書",
            Version = "v2",
            Description = "概要",
            Contact = new Contact() { Email = "fumiya.kume@homail.com", Name = "kuxu", Url = "Twitter.com/fumiya_kume" }
        });
});

**Configure++ の関数の中にも同様に追加します。

app.UseSwagger();

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Version1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "Version2");
});

確認

試しに実行してみましょう。

ローカルで実行すると以下のようなURLが自動で開かれると思います。

http://localhost:{ポート番号}/api/values

これを以下のように変更して 自動生成されたAPI仕様書を開いてみましょう。

http://localhost:{ポート番号}/swagger

f:id:kuxumarin:20170928093344p:plain

最後に

API仕様書を作成するのは基本的に人権がないのと等しいので自動化できると幸せみ高まりますね。

ASP.NET Core は非常に使いやすいフレームワークだなーというお気持ちです。