Create a help page for the ASP (reprint) Web API

Reprint Address: Http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

When you create a Web API, you often create a help page so that other developers know how to invoke your API. You can create all the documents manually, but it is best to automatically generate as many as possible.

To simplify this task, the ASP. NET Web API provides a library auto-generated help page.

Create an API help page

Install the update for ASP. NET and Web tools 2012.2. This update is integrated into the help page of 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 ValuesController a sample API controller named. The template also creates a help page for the API. all of the help page code files are placed in the project's regional folder.

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

This link is for you to take to the summary page of the API.

The MVC view of this page is defined in areas/helppage/views/help/index.cshtml. After you edit this page, you can modify the layout, Introduction, title, style, and so on.

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

The API column lists the HTTP methods and relative URIs. The Description column contains the documentation for each API. Initially, the document is just placeholder text. in the next section, I'll show you how to add a document from an XML comment.

Each API is linked to a webpage that provides more detailed information, including code for sample requests and responses.

Add a help page to an existing project

By using the NuGet Package Manager, you can add an existing Web API project to the help page.

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:

C # applications:Install-Package Microsoft.AspNet.WebApi.HelpPage

This command installs the necessary assemblies and adds a help page for the MVC view (located in the Area/helppage folder). You need to manually add a link to the help page. the URI is/help. to create a link in the Razor view, add the following:

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

also, be sure to register the area. in the Global.asax file, add the following code Application_Start method, if it does not already exist:

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

Add API Documentation

by default, the help page has a placeholder string for the file. You can use XML documentation to annotate documents that you can create. To enable this feature, open the Areas/helppage/app_start/helppageconfig.cs file and uncomment the following line:

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

now enable the XML document. In Solution Explorer, right-click the project and select Properties . Select the generated page.

depending on the output , check the XML document file . in the edit box, type "App_data/xmldocument.xml".

Next, open ValuesController The API controller, which defines the code in/controllers/valuescontroler.cs. Add some document comments to the Controller method. as An 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 you place the caret on the line above the method and type three slashes, Visual Studio will automatically insert the XML element. then you can fill in the blanks.

build and run the application again, and navigate to the help page. the document string should appear in the API.

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

Help pages are built on the Apiexplorer class, which is part of the Web API framework. the Apiexplorer class provides a provider for creating a help page. for each API, apiexplorer contains apidescription that describe some of the APIs. for This purpose, the "API" is defined as a combined HTTP method and a relative URI. For example, here are a few different APIs:

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

If a controller action supports multiple HTTP methods, Apiexplorer treats each method as a different API.

To hide the API from apiexplorer , add the apiexplorersettings property to the operation, and set the Ignoreapi to True.

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

You can also add this property to the controller to exclude the entire controller.

The Apiexplorer class obtains the document string from the Idocumentationprovider interface. as you can see earlier, the Help page library provides the Idocumentationprovider to get the file from the XML document string. The code is located in/areas/helppage/xmldocumentationprovider.cs. by writing your own Idocumentationprovider, you can get the document from another source. to bundle it up, define the setdocumentationprovider extension method in the helppageconfigurationextensions

Apiexplorer automatically calls the Idocumentationprovider interface to get the document string for each API. It stores them in the document properties of the apidescription and apiparameterdescription objects.

Create a help page for the ASP (reprint) Web API