Creating help Pages for ASP. NET Web API-excerpt from the network

When you create a Web API, it's often useful to create a help page, so this other developers would know how to call your a Pi. You could create any of the documentation manually, but it's better to autogenerate as much as possible.

To do this task easier, ASP. Provides a library for auto-generating help pages at run time.

Creating API Help Pages

Install ASP. Net. Web Tools 2012.2 Update. This update integrates help pages into the Web API project template.

Next, create a new ASP. NET MVC 4 project and select the Web API project template. The project template creates an example API controller named ValuesController . The template also creates the API help pages. All of the code files for the help page is placed in the areas folder of the project.

When you run the application, the home page contains a link to the API help page. From the home page, the relative path is/help.

This link brings a API summary page.

The MVC view for this page was defined in areas/helppage/views/help/index.cshtml. You can edit this page to modify the layout, Introduction, title, styles, and so forth.

The main part of the page was a table of APIs, grouped by controller. The table entries is generated dynamically, using the iapiexplorer interface. (I ' ll talk more about this interface later.) If you add a new API controller, the table was automatically updated at run time.

The "API" column lists the HTTP method and relative URI. The "Description" column contains documentation for each API. Initially, the documentation is just placeholder text. In the next section, I'll show you how to add documentation from XML comments.

Each API have a link to a page with Mroe detailed information, including example request and response bodies.

Adding help Pages to an Existing Project

You can add a existing Web API project by using the NuGet package Manager. This option is useful your start from a different project template than the "Web API" template.

From the Tools menu, select Library Package Manager, and then select Package Manager Console. In the Package Manager Console window, type one of the following commands:

For a C # application:Install-Package Microsoft.AspNet.WebApi.HelpPage

For a Visual Basic application:Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

There is packages, one for C # and one for Visual Basic. Make sure to use the one, matches your project.

This command installs the necessary assemblies and adds the MVC views for the Help pages (located in the areas/helppage fo Lder). You'll need to manually add a link to the help page. The URI is/help. To create a link in a razor view, add the following:

@Html. ActionLink ("API", "Index", "help", new {area = ""}, NULL)

Also, make sure to register areas. In the Global.asax file, add the following code to the Application_Start method, if it's not there already:

protectedvoidapplication_start(){//ADD This code, if not present.  arearegistration.  Registerallareas();    // ... }

Adding API Documentation

By default, the Help pages has placeholder strings for documentation. You can use XML documentation comments to create the documentation. To enable this feature, open the file Areas/helppage/app_start/helppageconfig.cs and uncomment the following line:

Config.  Setdocumentationprovider(newxmldocumentationprovider(HttpContext.  Current.  Server.  MapPath("~/app_data/xmldocument.xml"           )); 

Now enable XML documentation. In Solution Explorer, right-click the project and select Properties. Select the Build page.

Under Output, check XML documentation file. In the edit box, type "App_data/xmldocument.xml".

Next, open the code ValuesController for the API controller, which is defined In/controllers/valuescontroler.cs. Add Some documentation comments to the controller methods. For example:

<summary>Gets some very important data from the server.</summary>Public IEnumerable<string> Get(){ Return New String[] { "Value1",  "value2"  };}///<summary>/ Looks up some data by ID. ///</summary>///<param name= " ID ">the ID of the Data.</param>publicstring get (int Id) {   "value" ;               /span>                

Tip:if position the caret on the line above the method and type three forward slashes, Visual Studio automatically in Serts the XML elements. Then you can fill in the blanks.

Now build and run the application again, and navigate to the help pages. The documentation strings should appear in the API table.

The help page reads the strings from the XML file at run time. (When you deploy the application, make sure to deploy the XML file.)

Under the Hood

The help pages was built on top of the Apiexplorer class, which is part of the Web API framework. The Apiexplorer class provides provides the raw material for creating a help page. For each API, Apiexplorer contains a apidescription that describes the API. For this purpose, a "API" is defined as the combination of HTTP method and relative URI. For example, here is some distinct APIs:

• Get/api/products
• Get/api/products/{id}
• Post/api/products

IF A controller action supports multiple HTTP methods, the Apiexplorer treats each method as a distinct API.

To hide a API from the apiexplorer, add the apiexplorersettings attribute to the action and set IGN Oreapi to True.

[apiexplorersettings(ignoreapi=true)]publichttpresponsemessageGet( int ID){}              

You can also add this attribute to the controller and to exclude the entire controller.

The Apiexplorer class gets documentation strings from the Idocumentationprovider interface. As you saw earlier, the Help Pages library provides a Idocumentationprovider that gets documentation from XML do Cumentation strings. The code is located in/areas/helppage/xmldocumentationprovider.cs. You can get the documentation from another source by writing your own idocumentationprovider. To wire it up, call the setdocumentationprovider extension method, defined in helppageconfigurationextension S

Apiexplorer automatically calls into the Idocumentationprovider interface to get documentation strings For each API. It stores them in the documentation property of the apidescription and apiparameterdescription Objects.

Next Steps

You aren ' t limited to the help pages shown here. In fact, Apiexplorer are not limited to creating help pages. Yao Huang Lin have written some great blog posts to get you thinking out of the box:

• Adding a simple Test Client to ASP. Web API Help Page
• Making ASP. Web API help Page work on self-hosted services
• Design-time generation of help page (or client) for ASP. NET Web API
• Advanced Help Page Customizations

Creating help Pages for ASP. NET Web API-excerpt from the network