如何在Swashbuckle中添加API描述?

时间:2016-11-09 07:37:18

标签: c# asp.net-mvc api swagger swashbuckle

我是Swashbuckl或Swagger的新手,但我创建了一个Web API,需要使用Swagger从我的客户端创建文档。我已经创建了但是他们需要将API版本的详细信息显示在Swageer UI中,而我并不确定如何实现。

这是我的代码:

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

        GlobalConfiguration.Configuration
            .EnableSwagger(c =>
                {
                    c.SingleApiVersion("v1", "Demo Api");
                    c.IncludeXmlComments(string.Format(@"{0}\bin\WebApi.XML",
                                         System.AppDomain.CurrentDomain.BaseDirectory));
                })
        .EnableSwaggerUi();

    }
}

控制器示例:

     /// <summary>
    /// Get the Next IdKey
    /// </summary>
    /// <remarks>Get the Next IdKey from Dettagli Table</remarks>
    /// <response code="404">Not found</response>
    /// <response code="500">Internal Server Error</response>
    [HttpGet]
    public int GetNextIdDettagli()
    {
        try
        {
            DettagliRepo repo = new DettagliRepo();
            return repo.GetNextIdDettagli();
        }
        catch (Exception ex)
        {
            throw (ex);
        }
    }

这就是所有Controller操作的完成方式。

以下是我的Swagger UI的输出:

enter image description here

这是我的客户的预期输出,标记为1,2和3:

enter image description here

我可以从屏幕截图中了解到他们希望显示API描述,标题和其他信息,但我不知道如何显示它们。请帮助我或建议我如何实现这一部分。提前谢谢。

更新

我已经从Following link

取得了1和2

使用以下代码:

                   .EnableSwagger(c =>
    {
        c.RootUrl(req => GetRootUrlFromAppConfig());

        c.Schemes(new[] { "http", "https" });

        c.SingleApiVersion("v1", "Swashbuckle.Dummy")
            .Description("A sample API for testing and prototyping Swashbuckle features")
            .TermsOfService("Some terms")
            .Contact(cc => cc
                .Name("Some contact")
                .Url("http://tempuri.org/contact")
                .Email("some.contact@tempuri.org"))
            .License(lc => lc
                .Name("Some License")
                .Url("http://tempuri.org/license"));
    });

但我仍然需要帮助第3点。谢谢。

1 个答案:

答案 0 :(得分:7)

您实际上可以使用文档过滤器创建文档过滤器并更新swagger文档中的Tags节点。

请参阅下面的示例文档过滤器:

public class DocumentFilter : IDocumentFilter
{
    /// <summary>
    /// This method is for applying the filter
    /// </summary>
    /// <param name="swaggerDoc">Swagger Document</param>
    /// <param name="schemaRegistry">Schema Registry</param>
    /// <param name="apiExplorer">API Explorer</param>
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        var methods = swaggerDoc.paths.Select(i => i.Value);
        List<string> tags = new List<string>();
        foreach (var method in methods)
        {
            if (method.delete != null)
            {
                tags.AddRange(method.delete.tags);
            }

            if (method.get != null)
            {
                tags.AddRange(method.get.tags);
            }

            if (method.put != null)
            {
                tags.AddRange(method.put.tags);
            }

            if (method.post != null)
            {
                tags.AddRange(method.post.tags);
            }

            if (method.patch != null)
            {
                tags.AddRange(method.patch.tags);
            }                
        }

        swaggerDoc.tags = new List<Tag>();
        foreach (var tag in tags)
        {
            swaggerDoc.tags.Add(new Tag() { name = tag, description = "This is a group of methods for " + tag });
        }
    }
}