BETA

ASP.NET CoreでSwaggerしてみる

投稿日:2018-12-22
最終更新:2018-12-22

まず最初に土下座しておくと、Swagger実は今日しりました(;´∀`)
その勉強の履歴という事で・・・・。

Swaggerとは

私はこの辺を見てSOAPを思い出しました。
いずれにせよ仕様を定義・参照できる共通仕様があるというのはよいなぁと思いちょっとASP.NET Coreでやってみました。

作成するもの

ASP.NET CoreのWebAPIのテンプレートをベースに、Swaggerの設定をします。
その際SwaggerのUIを使えるように、またAPIの説明に関してはC#のコメント部分から取得できるようにします。
一部ソースは上記の参考サイトのコピペ部分があったりします。

下準備(プロジェクト作成、パッケージ追加)

いつものdotnetコマンドで準備していきます。今回はWebAPIを作成するのでテンプレートはwebapiを使用しています。
SwaggerのパッケージとしてSwashbuckle.AspNetCoreを使用しています。

dotnet new webapi  
dotnet add package Swashbuckle.AspNetCore  

Swaggerの設定

主にStartup.csを修正します。ただし、コメントから仕様を作成する都合上、
コメント部分からXMLドキュメントを生成するためにプロジェクトの設定を変更します。

Startup.CS(ConfigureServices)

public void ConfigureServices(IServiceCollection services)  
{  
        services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);  

        //Swaggerの設定をします  
        services.AddSwaggerGen(c =>  
        {  
                //Swaggerの対象にするコントローラを選別します  
                c.DocInclusionPredicate((name, apiDescription) =>  
                {  
                        var controllerActionDescription = apiDescription.ActionDescriptor as ControllerActionDescriptor;  
                        // コントローラ名に Api が含まれていたらSwaggerの対象にする  
                        return controllerActionDescription?.ControllerName.Contains("Api") ?? false;  
                });  

                // XMLファイルのパスを取得  
                var xmlPath = Path.Combine(System.AppContext.BaseDirectory, System.Reflection.Assembly.GetEntryAssembly().GetName().Name + ".xml");  

                // XMLファイルをドキュメントコメントとして登録  
                c.IncludeXmlComments(xmlPath);  

                //ドキュメントの設定(最小限の設定であればこの行だけでOK)  
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });  
        });  
}  

Startup.CS(Configure)

public void Configure(IApplicationBuilder app, IHostingEnvironment env)  
{  
        if (env.IsDevelopment())  
        {  
                app.UseDeveloperExceptionPage();  
        }  
        else  
        {  
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.  
                app.UseHsts();  
        }  

        app.UseHttpsRedirection();  
        app.UseMvc();  

        /*  
         * ここからSwagger用に追加  
         */  
        app.UseSwagger();  
        app.UseSwaggerUI(c =>  
        {  
                c.RoutePrefix = "api-docs";   
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");  
        });  
}  

プロジェクトファイルの修正(xxxxx.csproj)

  <PropertyGroup>  
    <TargetFramework>netcoreapp2.2</TargetFramework>  
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>  
    <!-- ここから追加します -->  
    <GenerateDocumentationFile>true</GenerateDocumentationFile>  
    <NoWarn>$(NoWarn);1591</NoWarn>  
    <!-- ここまで -->  
    </PropertyGroup>  

APIの定義

実際にAPIを定義します。
基本的には通常通りコントローラを作成してコメントをつけるだけとなります。
ただし、受け取るパラメータに関しては[FromQuery]などアノテーションが必要そうです。
この辺はよくわかっていないので、勉強が必要そうです(;´∀`)

    [Route("api/[controller]")]  
    [ApiController]  
    public class ValuesApiController : ControllerBase  
    {  
            // GET api/values  
            /// <summary>  
            /// テストのAPI  
            /// </summary>  
            /// <param name="inputstr">入力パラメータ</param>  
            /// <returns></returns>  
            [HttpGet]  
            public ActionResult<IEnumerable<string>> Get([FromQuery]string inputstr)  
            {  
                    return new string[] {  inputstr };  
            }  
    }  

では確認してみます。

https://localhost:5001/api-docsへアクセスします。

こんな感じにAPIの仕様目視、確認が可能です。
またエンドポイントのJSON(例: /swagger/v1/swagger.json)アクセスするとJSON形式でAPIの情報が取得できます。

感想など

ぶっちゃけよくわかってないまま進めましたけど、簡単に動作確認できるのはうれしいですね。
あとこの、定義のJSONクライアント側のコードを自動生成できたりするのだろうか・・・・とか調べるところはまだまだありそうです。

技術ブログをはじめよう Qrunch(クランチ)は、プログラマの技術アプトプットに特化したブログサービスです
駆け出しエンジニアからエキスパートまで全ての方々のアウトプットを歓迎しております!
or 外部アカウントで 登録 / ログイン する
クランチについてもっと詳しく

この記事が掲載されているブログ

@saitooooの技術ブログ

よく一緒に読まれる記事

0件のコメント

ブログ開設 or ログイン してコメントを送ってみよう
目次をみる
技術ブログをはじめよう Qrunch(クランチ)は、プログラマの技術アプトプットに特化したブログサービスです
or 外部アカウントではじめる
10秒で技術ブログが作れます!