Discovering your Web API
Thu, Sep 27 2012 22:47
If your ASP.NET Web API service is on the 'net and no one is around to explain it, does it provide a service? Unlike no one hearing the tree falling in the woods, this question is more than a philosophical thought experiment. It could be a big issue for the clients needing your service.
[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]
Once you have a Web API service in place, clients can call it. But there is no easy way for those clients to discover the available service methods or their parameters. What they need is a way to view your API.
That's where the Help Page comes in to help you help them. As it states in the dialog below, "The ASP.NET Web API Help Page automatically generates help page content for the Web APIs on your site."
The Help Page is available as a NuGet Package. To install it:
1) Select your Web API service project in Solution Explorer.
2) Select Project | Manage NuGet Packages from the Visual Studio menu.
3) Search for "helppage" using the search box in the upper right corner of the resulting dialog.
4) Click the Install button next to the Microsoft ASP.NET Web API Help Page.
This package adds an Areas directory into the project which contains all of the generated code:
That's it. After you install it you don't have to do anything else.
To view the generated help page, launch your Web API service in Visual Studio and append "/help" to the url in the Address bar of the browser. The generated help page is displayed.
Notice that it contains the name of the controller and descriptions of the two methods in the Web API service.
Click on an action name to drill down. The details provide information on the parameters, if any, and the response body formats. It even contains an example response.
Since all of the code for these help pages are generated into your project, you can easily change them. You can style the layout and change the textual content as desired.
Use the Help Page NuGet package any time you want to provide documentation to the clients of your Web API service.