Web API 2 Getting Started--creating the help page for the ASP (Google Translate)

in this article

1. Create an API help page
2. Add a help page to an existing project
3. Add API Documentation
4. Under the hood.
5. Next

Mike Wasson

when creating a Web API, it is often useful to create help pages so that other developers know how to invoke the API. You can create all your documents manually, but it's best to generate them automatically as much as possible.

To simplify this task, the ASP. NET WEB API provides a library for automatically generating help pages at run time.

Create an API help page

installation Asp. NET and Web Tools 2012.2 updates . This update integrates the 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 named API ValuesController . The template also creates an API help page. All code files for the help page are placed in the project's regional folder.

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

This link will take you to the API summary page.

The MVC view of the page is defined in areas/helppage/views/help/index.cshtml. You can edit this page to modify the layout, Introduction, title, style, etc.

The main part of the page is the API table grouped by the controller. dynamically generate table entries using the Iapiexplorer interface . (I'll talk about this interface later.) If a new API controller is added, the table will be updated automatically 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 has a link to a page that contains more detailed information, including sample request and response entities.

Add a Help page to an existing project

You can use the NuGet Package Manager to add help pages to an existing Web API project. This option is useful when you start with a different project template for the Web API template.

from The Tools menu, select Library Package Manager , and then select the Package Manager console . in the Manager Manager window, type one of the following commands:

for C # Applications:Install-Package Microsoft.AspNet.WebApi.HelpPage

for Visual Basic Applications:Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

There are two packages, one for C # and one for visual Basic. Make sure that you use a match to your project.

This command installs the necessary assemblies and adds an MVC view to the help page (located in the Areas/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:

CSHTML replication

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

Also, be sure to register the zone. in the Global.asax file, add the following code to the Application_Start method (if not yet):

C # replication

protected void Application_Start(){ // Add this code, if not present. AreaRegistration.RegisterAllAreas(); // ...}

Add API Documentation

by default, the help page has a placeholder string for the document. You can use XML document annotations to create documents. To enable this feature, open the file area/Helppage/app_start/helppageconfig.cs and uncomment the following line:

C # replication

config.SetDocumentationProvider(new XmlDocumentationProvider(    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 Build page.

under Output , examine the XML document file . in the edit box, type "App_data/xmldocument.xml". 1

Next, open ValuesController The code for the API Controller , which is defined in/controllers/valuescontroler.cs. Add some document comments to the Controller method. For example:

C # replication

///<summary>Gets some very important data from the server.///</summary>Public ienumerable<String>Get (){ReturnNewstring[] { "value1",  "value2"}; ///<summary>///Looks up some data by Id. ///</summary>///<param name=" id ">the ID of the Data. </param>public string Span class= "Hljs-title" >get (int ID) { return  "value";}        

Note

tip: If you place the caret above the method and type three forward slashes, Visual Studio will automatically insert the XML element. then you can fill in the blanks.

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

the help page reads the string from the XML file at run time. (when deploying an application, be sure to deploy an XML file.) )

under the hood .

The help page is built on Above the Apiexplorer class , This class is part of the Web API framework. the apiexplorer class provides the raw material used to create a help page. for each API,apiexplorer contains a apidescription that describes the API . to do this, define "API" as a combination of HTTP methods and relative URIs. For example, here are some different APIs:

• GET/API/Products
• Get/api/products/{ID}
• POST/API/Products

if the controller operation supports multiple HTTP methods, the Apiexplorer Each method as a different API.

to from Apiexplorer the API , Add the apiexplorersettings property to the operation, and ignoreapi is set to True.

C # replication

[ApiExplorerSettings(IgnoreApi=true)]public HttpResponseMessage Get(int id) { }

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

Apiexplorer class from The Idocumentationprovider interface gets the document string . As mentioned earlier, the help page library provides a idocumentationproviderthat gets the document from the XML document string. The code is in/areas/helppage/xmldocumentationprovider.cs. You can get documents from other sources by writing your own Idocumentationprovider . to connect to it, call the Setdocumentationprovider extension method, Defined in Helppageconfigurationextensions

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

Web API 2 Getting Started--creating the help page for the ASP (Google Translate)