前書き
API 仕様書作るのつらい
複数人で共同開発をしていて、APIの仕様を伝えなければいけない時がやってきます。
そんな時に Excel に書き込んで共有していてはいろいろつらそうなので簡単にAPIの仕様や使い方を共有できるツールの Swagger というものが存在します。
Swagger を心込めてお手製するのつらい
さて、 Swagger を使ってドキュメント等を作成していきましょう!
という流れになっても Swagger でドキュメントを製作するためには、 YAML ファイル or Json ファイルを編集する必要があります。 しかし、私は怠惰です。 いちいち Json ファイルを編集するのもいやだし、APIの仕様変更に合わせて書き換えるのも嫌です。
だから私は、API仕様書を自動生成する
本題
さて、本題に入っていきましょう
環境
今回使用した環境は以下の通りとなっています。
- Windows 10
- Visual Studio 2017 15.3
- .NET Core SDK 2.0
実際に編集していく
ASP.NET Core web API 2.0 な環境でプロジェクトを作成してください。
Nuget から必要なパッケージをインストールしていく
Nuget パッケージで 検索して入れてください。
Swashbuckle.AspNetCore
コーディング!
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
最後に
API仕様書を作成するのは基本的に人権がないのと等しいので自動化できると幸せみ高まりますね。