CODEWITHSUNDEEP
c#.netswagger
Casey Crookston
Casey Crookston

Reputation: 13955

Adding comments to endpoints with Swagger

I'm using Swagger / Swashbuckle for my API. I want the Swagger UI to show the method descriptions. In their documents it says:

2 - Configure Swashbuckle to incorporate the XML comments on file into the generated Swagger JSON:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

Can someone please explain this? What I am supposed to do with this code? Do I copy and paste it somewhere? If so, where?

(.NET Framework 4.7)

EDIT:

The answer by Jawad below led me to the solution. In the original SwaggerConfig.cs file, there was this:

// If you annotate Controllers and API Types with
// Xml comments (http://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx), you can incorporate
// those comments into the generated docs and UI. You can enable this by providing the path to one or
// more Xml comment files.
//
//c.IncludeXmlComments(GetXmlCommentsPath());

I was unclear on how to change that last line to add my XML file. This worked:

c.IncludeXmlComments(Path.Combine(System.AppContext.BaseDirectory, "bin\\KGC.API.xml"));

I also had to add using System.IO.

Upvotes: 3

Views: 6492

Answers (1)

Jawad
Jawad

Reputation: 11364

The way i have done it is by updating the SwaggerConfig.cs file .. 

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

        GlobalConfiguration.Configuration
            .EnableSwagger("docs/{apiVersion}", c =>
            {
                c.SingleApiVersion("v1", "Title Of API");
                c.Schemes(new List<string> { "http", "https" });
                c.UseFullTypeNameInSchemaIds();
                c.IncludeXmlComments(Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml"));
            });
    }

Last line in the code above enabled the XML comment tagging.

One other thing you have to do is,

  1. Go to Properties of Project (not Solution)
  2. Build / Output -> Add path to XML Documentation File.

For Reference Purposes, this was quite helpful.

Upvotes: 2

Related Questions