Swashbuckleを使用してWebAPIのSwaggerドキュメントからメソッドを省略する方法


135

C#ASP.NET WebAPIアプリケーションを使用しており、APIドキュメントはSwashbuckleを使用して自動的に生成されます。ドキュメントから特定のメソッド省略できるようにしたいのですが、SwaggerにSwagger UI出力に含めないように指示する方法を理解できていないようです。

これはモデルまたはスキーマフィルターの追加に関係しているように感じますが、何をすべきかが明確ではなく、ドキュメントはメソッドの出力を変更する方法の例を提供するだけで、出力から完全に削除することはないようです。

前もって感謝します。

回答:


337

次の属性をコントローラーとアクションに追加して、生成されたドキュメントからそれらを除外できます。 [ApiExplorerSettings(IgnoreApi = true)]



4
これをプログラムで行う方法はありますか?構成設定に従って、一部の環境ではAPIを公開したいが他の環境では公開したくない。
Paul Kienitz、2018

@SyaifulNizamYahyaわかりません。たぶん[JsonIgnore]?
mikesigs

@mikesigsはい[JsonIgnore]は機能します。残念ながら、それはシリアライズを禁止します。
Syaiful Nizam Yahya 2018

4
スワッシュバックルのドキュメント:任意操作の省略
spottedmahn

17

誰かがgithubにソリューションを投稿したので、ここに貼り付けます。すべてのクレジットは彼に行きます。https://github.com/domaindrivendev/Swashbuckle/issues/153#issuecomment-213342771

最初に属性クラスを作成する

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class HideInDocsAttribute : Attribute
{
}

次に、ドキュメントフィルタークラスを作成します。

public class HideInDocsFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        foreach (var apiDescription in apiExplorer.ApiDescriptions)
        {
            if (!apiDescription.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<HideInDocsAttribute>().Any() && !apiDescription.ActionDescriptor.GetCustomAttributes<HideInDocsAttribute>().Any()) continue;
            var route = "/" + apiDescription.Route.RouteTemplate.TrimEnd('/');
            swaggerDoc.paths.Remove(route);
        }
    }
}

次に、Swagger Configクラスで、そのドキュメントフィルターを追加します。

public class SwaggerConfig
{
    public static void Register(HttpConfiguration config)
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        config
             .EnableSwagger(c =>
                {
                    ...                       
                    c.DocumentFilter<HideInDocsFilter>();
                    ...
                })
            .EnableSwaggerUi(c =>
                {
                    ...
                });
    }
}

最後のステップは、Swashbuckleにドキュメントを生成させたくないコントローラーまたはメソッドに[HideInDocsAttribute]属性を追加することです。


1
RemoveRouteは私が探しているドロイドかもしれないと思います。
Paul Kienitz、2018

13

ドキュメントフィルターを使用して生成された後、swaggerドキュメントから「操作」を削除できます。動詞をに設定するだけnullです(ただし、他の方法で実行することもできます)。

次のサンプルはGET動詞のみを許可し、この問題から引用しています。

class RemoveVerbsFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        foreach (PathItem path in swaggerDoc.paths.Values)
        {
            path.delete = null;
            //path.get = null; // leaving GET in
            path.head = null;
            path.options = null;
            path.patch = null;
            path.post = null;
            path.put = null;
        }
    }
}

そしてあなたのswagger設定で:

...EnableSwagger(conf => 
{
    // ...

    conf.DocumentFilter<RemoveVerbsFilter>();
});

1
注:コメントを外してもパスは削除されません。path.get = null;その結果、これらのパスはSwaggerファイルに含まれますが、詳細は含まれません。ApiExplorerSettingsAttributeGitHubの元の返信で述べたように、を回答に含める方がよい場合があります。ApiExplorerSettingsを使用すると、タイプ情報がSwaggerファイルのschemesリストに追加されない場合もあります。
JBert 2016

7

パスアイテムの辞書エントリを完全に削除したいと思います。

var pathsToRemove = swaggerDoc.Paths
                .Where(pathItem => !pathItem.Key.Contains("api/"))
                .ToList();

foreach (var item in pathsToRemove)
{
    swaggerDoc.Paths.Remove(item.Key);
}

このアプローチでは、生成されたswagger.json定義で「空の」アイテムを取得しません。


3

フィルターを作る

public class SwaggerTagFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach(var contextApiDescription in context.ApiDescriptions)
        {
            var actionDescriptor = (ControllerActionDescriptor)contextApiDescription.ActionDescriptor;

    if(!actionDescriptor.ControllerTypeInfo.GetCustomAttributes<SwaggerTagAttribute>().Any() && 
    !actionDescriptor.MethodInfo.GetCustomAttributes<SwaggerTagAttribute>().Any())
            {
                var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
            swaggerDoc.Paths.Remove(key);
            }
        }
    }
}

属性を作成する

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class SwaggerTagAttribute : Attribute
{
}

startup.csで適用

 services.AddSwaggerGen(c => {
            c.SwaggerDoc(1,
                new Info { Title = "API_NAME", Version = "API_VERSION" });
            c.DocumentFilter<SwaggerTagFilter>(); // [SwaggerTag]
        });

Swagger JSONに含めるメソッドとコントローラーに[SwaggerTag]属性を追加します


甘い。適切なアプローチとslnを共有していただきありがとうございます。
VedranMandić19年

2

誰かを助けるかもしれませんが、開発中(デバッグ中)コントローラとアクション全体を公開し、本番(リリースビルド)中にこれらを非表示にするのが好きです

#if DEBUG
    [ApiExplorerSettings(IgnoreApi = false)]
#else
    [ApiExplorerSettings(IgnoreApi = true)]
#endif  

1

@spottedmahnsの回答に基づく。私の仕事はその逆でした。許可されているものだけを表示します。

フレームワーク:.NetCore 2.1; Swagger:3.0.0

追加された属性

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class ShowInSwaggerAttribute : Attribute
{
}

そしてカスタムIDocumentFilterを実装する

public class ShowInSwaggerFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {

        foreach (var contextApiDescription in context.ApiDescriptions)
        {
            var actionDescriptor = (ControllerActionDescriptor) contextApiDescription.ActionDescriptor;

            if (actionDescriptor.ControllerTypeInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any() ||
                actionDescriptor.MethodInfo.GetCustomAttributes<ShowInSwaggerAttribute>().Any())
            {
                continue;
            }
            else
            {
                var key = "/" + contextApiDescription.RelativePath.TrimEnd('/');
                var pathItem = swaggerDoc.Paths[key];
                if(pathItem == null)
                    continue;

                switch (contextApiDescription.HttpMethod.ToUpper())
                {
                    case "GET":
                        pathItem.Get = null;
                        break;
                    case "POST":
                        pathItem.Post = null;
                        break;
                    case "PUT":
                        pathItem.Put = null;
                        break;
                    case "DELETE":
                        pathItem.Delete = null;
                        break;
                }

                if (pathItem.Get == null  // ignore other methods
                    && pathItem.Post == null 
                    && pathItem.Put == null 
                    && pathItem.Delete == null)
                    swaggerDoc.Paths.Remove(key);
            }
        }
    }
}

ConfigureServicesコード:

public void ConfigureServices(IServiceCollection services)
{
     // other code

    services.AddSwaggerGen(c =>
    {
        // other configurations
        c.DocumentFilter<ShowInSwaggerFilter>();
    });
}

アレハ、ありがとう。このアプローチは、ApiExplorerSettingsAttributeが機能しないSwashBuckle.ODataに対して実際に適切に機能します。
Prasad Korhale、

1

1行SwaggerConfig c.DocumentFilter();を追加します。

public class HideInDocsFilter : IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        { 
var pathsToRemove = swaggerDoc.Paths
                .Where(pathItem => !pathItem.Key.Contains("api/"))
                .ToList();

foreach (var item in pathsToRemove)
{
    swaggerDoc.Paths.Remove(item.Key);
}
    }
}

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.