Add documentation to your Web API in 5 steps
APIs are created to expose the system to other developers, so we need to provide documentation that explain how to use our API.
So far, so good, but maintain documents manually is a kind of boring. What about auto-generate it?
Well, if you are using ASP.NET Web API this is a piece of cake.
How to add documentation to your ASP.NET Web API?
- Install "Microsoft.AspNet.WebApi.HelpPage" package from nuget. (If you are using VB.NET install "Microsoft.AspNet.WebApi.HelpPage.VB"). This package will create an Area called "Help" in the API project.
- Make sure that you have the following code in the "Application_Start" method at your Global.asax file: AreaRegistration.RegisterAllAreas();
- Documentation will be available in the /Help URI. So, just add a link to it in your application.
- To enable the XML Documentation comments, open the file Areas/HelpPage/App_Start/HelpPageConfig.cs and uncomment the line "config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));"
- In Solution Explorer, right-click the project, select Properties, then go to the Build page. In the Output section check the XML documentation file property and set the text box with the value "App_Data/XmlDocument.xml".
Now you are able to start adding comments to your Web API methods, as you can see in the following example:
/// Get text by ID
/// <param name="id">ID used to get the result text.</param>
public string Get(int id)
Build your application and you are done! Now, if you want to do some advanced stuff, I recommend that you take a look into the following posts:
- Creating Help Pages for ASP.NET Web API
- Advanced Help Page customizations
- Introducing the ASP.NET Web API Help Page
I hope this helps you.