WebAPIでSwaggerを使う

C#のWebAPIで Swashbuckle を使ってAPIの使用を生成するというブログのエントリは良く検索で見つかるのですが、１つのコントローラーにGETを２つ作ってしまった場合の対応がまとまっているところがなかったので、自分で調べた結果を書いておきます。

SwaggerConfig.csの設定

c.SchemaId(x => x.FullName)の設定を追加。

c.ResolveConflictingActions を追加して、メソッドが重複した場合 First()でどれか1つを採用する対応もあったが、今回はGETを２つとも表示したいので、そもそも ResolveConfilitingActions では対応できない。

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;
    GlobalConfiguration.Configuration
        .EnableSwagger((c) =>
        {
            
            c.SingleApiVersion("v1", "MyAPI");
            c.OperationFilter<GlobalHttpHeaderFilter>();
            c.IncludeXmlComments(GetXmlCommentsPath());
            c.SchemaId(x => x.FullName);
        })
        .EnableSwaggerUi(c =>
        {
        });
}

Routeの追加

衝突が発生する同じメソッドタイプの関数に Routeで明確に名前を付けておく。

[Route("Func1")]
public async Task<MyResponse> GetFuncAsync(string str)
          
[Route("Func2")]
public async Task<MyResponse> GetExFuncAsync(int x, string str)

JSONで表示

IISを起動して、以下のURLに接続しAPI定義をJSONデータを表示させる。
このとき、上の２つの手順を踏まないとエラーになる。

https://localhost:8443/swagger/docs/v1
（プロトコルとポート番号は自分の環境に合わせる）

API仕様書の作成

redoc-cliというツールを使うとJSONフォーマットのSwaggerからhtmlのAPI仕様書を作成できるので、以下のように作成。

github.com

# npm install -g redoc-cli
# redoc-cli bundle MyApi.json -o apidocs/index.html