sqmrog
Last Updated: February 25, 2016
·
9.652K
· blaiseliu
0 zdfer mextupleu3bexrr3szkfrkbdj3chrcr3youxf8zsotmf0kvtoxe7u7xapdqodnqquhhlpg

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?!

Say Thanks
Respond

1 Response
Add your response

23081
0 itf3qv 2ccqot pp31hyqz gzqiu 5sps9ryqzg2o ced3sy7n0ds4ngrh 5lcurgld0r0pa2uv4

Thanks...

over 1 year ago ·