Swashbuckle.webapi: Question: How do I document a controller

[danpetitt]

The PetStore example on Swagger UI has a description for the actual controller "Pet" has "everything about pets".

I couldnt find a way of documenting this myself, as summary XML comment on the controller doesn't work so I presume its maybe a new thing in Swagger UI v3?

[danpetitt]

Looks like swagger format contains 'tags' which describe these controllers so we need to somehow get the XML comment for a member to output as tags so we can get them into the UI:

tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user
    externalDocs:
      description: Find out more about our store
      url: 'http://swagger.io'

[heldersepu]

Let me try this on my test site, let see...
Did you get your VisualStudio up and running with the Swashbuckle solution?

[heldersepu]

I added comments to one of the test controllers:
http://swashbuckletest.azurewebsites.net/XmlComments.XML
As you can see the controller and 2 methods have comments...

but on http://swashbuckletest.azurewebsites.net/swagger/docs/v1 it does NOT shows the comment for the controller

[danpetitt]

Correct, swashbuckle needs to support it I guess and output it into the swagger doc ready for SwaggerUI to use.

[heldersepu]

The question is where in the swagger docs should that go?

{
    "swagger": "2.0",
    "info": {
        "version": "v1",
        "title": "Swagger_Test"
    },
    "host": "swashbuckletest.azurewebsites.net",
    "schemes": ["http"],
    "paths": {
        "/api/ApiExplorer": {},
        "/attrib/{name}": {},
        "/bind/{id}": {},
        "/api/Default": {},
        "/api/Default/{id}": {},
        "/api/Dictionary": {},
        "/api/TestEnum": {},        
    },
    "definitions": {}
}

Because the paths are direct link to the actions not the controller as you can see on my example there are two "/api/Default" & "/api/Default/{id}" those are both paths to the same controller

[danpetitt]

It goes between host and schemes in the PetStore example

[danpetitt]

tags is an array of objects with name, description and externaldocs properties where externaldocs is an object with name and url properties:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tagObject
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#externalDocumentationObject

I guess your api/default routes are routes to the same method in one class/controller. So that is already handled isnt it?

[mahichr]

There is an includeControllerXmlComments bool param in IncludeXmlComments method you can pass to document xml comments in SwaggerUI.

SwaggerGen Configuration

    services.AddSwaggerGen(c =>
    {
        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
    });

Controller Class

    /// <summary>
    /// My awesome values controller class
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        /// <summary>
        /// Gets values
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }
    }

Swagger UI

[gohalien]

There is an includeControllerXmlComments bool param in IncludeXmlComments method you can pass to document xml comments in SwaggerUI.

SwaggerGen Configuration

    services.AddSwaggerGen(c =>
    {
        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
    });

Controller Class

    /// <summary>
    /// My awesome values controller class
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        /// <summary>
        /// Gets values
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }
    }

Swagger UI

There is no plan to migrate this to non asp net core swashbuckler right ?

[mukeshagarwal-gep]

I am able to see the controller xml document summary as description of controller tag, thats awesome. How I add external docs properties to the controller tag? I am trying to add detailed documentation link into the swagger page for the tag.

tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'