如何在Swashbuckle中添加API描述？

I'm new in Swashbuckl or Swagger but I've created a Web API which requires to create Documentation using Swagger from my client. I've already created but they require the API version details to be shown into the Swageer UI which I'm not so sure how to achieve.

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

Here is my code:

这是我的代码:

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();

    }
}

Controller Example:

     /// <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);
        }
    }

This is how all of the Controller actions has been made.

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

Here is the output of my Swagger UI:

这是我的Swagger UI的输出:

This is the expected output from my client marked by 1,2 and 3:

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

I can understand from the screen shot that they want API description, title and other information to be shown but I don't know how to show them. please help me or suggest me how do I achieve that part. Thanks in advance.

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

Update

I've achieved 1 and 2 from the Following link

我从以下链接中获得了1和2

with the following code:

使用以下代码:

                   .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"));
    });

But still I need help for the point 3. Thanks.

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

1 个解决方案

#1

You can actually create a document filter and update the Tags node in the swagger document using the document filter.

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

See a sample document filter below:

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

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 });
        }
    }
}

#1