Last Updated: September 30, 2021
·
38.71K
· blaiseliu

3 easy steps to create WebAPI documentations

By default, the API Help page created by Microsoft.AspNet.WebApi.HelpPage contains no documentation. We will see all ApiController actions are listed with No documentation available.

Picture

To enable the documentation, we just need to follow three easy steps.

Step 1 - on the controller level

For the testing purpose, a new ApiController is created, named DocumentationsController.

public class DocumentationsController : ApiController
{
    // GET api/documentation
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
....

Hit /// ahead of the controller action to get the documentation.

// GET api/documentation
/// <summary>
/// This is how we create a documentation
/// </summary>
/// <returns></returns>
public IEnumerable<string> Get()
....

For more information on what can be documented, you can hit "<" to bring out IntelliSense, or go to the MSDN page.

Step 2 - Build Property

Bring out the Project Properties page and set up the xml output for documentation. In this example, the documentation file would be App_Data\Documentation.XML.

Picture

Step 3 - HelpPage Config

To set up the HelpPageConfig to use our documentation xml file, go to ~\Areas\HelpPage\HelpPageConfig.cs.

By default, the config.SetDocumentationProvider statement is commented out. Use that statement, and point the location of DocumentationProvider to our xml file:

public static void Register(HttpConfiguration config)
{
    // Uncomment the following to use the documentation from XML documentation file.
    config.SetDocumentationProvider(
        new XmlDocumentationProvider(
            HttpContext.Current.Server.MapPath("~/App_Data/Documentation.xml")));

Now we can do a build and refresh the api documenation page:

Picture

Of course, the documentation file is created also:

Picture

Notice the documentation is correct displayed. Pretty easy, huh?!

2 Responses
Add your response

Thanks...

over 1 year ago ·

For my action it's really works, but for the recive properties? What can i do?

over 1 year ago ·