Generate Description Fields for Body Parameters

Question

So I've been Googling a lot to try and solve this problem but I can't seem to find anything on it. See picture for reference, but I'm trying to fill in the Description field for the body parameters. What is the best way to do this?

Answer 1

Alright so I figured this out, hopefully this can help someone else who comes across this. The first thing you want to do is follow this link to enable XML Documentation for ApiExplorer. After you enable that you want to add

/// <summary>Description</summary>

Above your controller names (you can add param names as well in your xml by adding another line <param name="model">A Test Model</param>)

Then head to your models and for each parameter inside your model add a summary tag again, like so:

public class TestModel()
{
/// <summary>This is your IdNumber you received earlier</summary>
public string IdNumber {get;set;}
}

Answer 2

You can add a Description attribute:

[Description("Get the data from our service. It will requires a key.")]
public ActionResult GetData(string key)
{
  //Do something here...
  return Json(new{Success=true, Data = data});
}

Or for the parameters

public ActionResult GetData([Description("A valid key should be formated as xxx-xxx-xx")]string key)
{
  //Do something here...
  return Json(new{Success=true, Data = data});
}

From: http://millionbonus.bitbucket.org/mvc.apiexplorer/

Answer 3

1. Right-click on the project, click on Properties -> Build -> click on the XML build as shown in the pic.

2. Go to Areas folder in the project -> App_Start -> HelpPageConfig.cs

3. Uncomment the below line if commented.

   config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/projectname.xml")));

4. Change the MapPath file name with the one given in Build XML documentation file column. *projectname will be changed to your project name.

Answer 4

I found the answers here confusing so here is my complete solution.

First turn on XMLDocumentation by going to Areas -> HelpPage -> App_Start -> HelpPageConfig.cs and uncommenting out the following two lines.

// Uncomment the following to use the documentation from XML documentation file.
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Then for the method that you want to provide documentation for create an xml comment in the following format. This is usually autocompleted for me but I have resharper turned on so that may not be the default.

    /// <summary>
    /// An example method description
    /// </summary>
    /// <param name="id">An example parameter description</param>
    /// <returns>An example return value description</returns>
    // GET: api/Products/5
    public string Get(int id)
    {
        return "value";
    }

If you run the app and go to your api help page, the documentation should be visible.