ASP. NET web api rc version new feature: web API help document creation

On infoq, I used iapiexplorer to list ASP. net web API. The version of this article is ASP. net web API beta version write, iapiexplorer is already included in the RC version, and found ASP. the RC version of Net web API httpconfiguration has one more attribute than the beta version:

Public defaultservices services {Get; internal set ;}

Debug, you can see that there are 18 services by default, iapiexplorer is one of them:

You can use this API to complete the following tasks:

• Generate document
• Create machine-readable metadata
• Create a test Client

Microsoft employee Yao published two articles (Asp. net web API: introducing iapiexplorer/apiexplorer and ASP. net web API: generating a web API help page using apiexplorer) is used to display how to use the API to print the web API list and how to create a help document.

Therefore, we create a help document to refer to this article for the ASP. net web API: generating a web API help page using apiexplorer; the author has implemented an idocumentationprovider in the article, which is generated through the annotation XML document of the Code, this is a very good implementation:

Public class xmlcommentdocumentationprovider: idocumentationprovider
{
Xpathnavigator _ documentnavigator;
Private const string _ methodexpression = "/doc/members/member [@ name ='m: {0} ']";
Private Static RegEx nullabletypenameregex = new RegEx (@"(. *\. nullable) "+ RegEx. escape ("'1 [[") + "([^,] *),. *");
Public xmlcommentdocumentationprovider (string documentpath)
{
Xpathdocument XPath = new xpathdocument (documentpath );
_ Documentnavigator = XPath. createnavigator ();
}
Public Virtual string getdocumentation (httpparameterdescriptor parameterdescriptor)
{
Reflectedhttpparameterdescriptor reflectedparameterdescriptor = parameterdescriptor as reflectedhttpparameterdescriptor;
If (reflectedparameterdescriptor! = NULL)
{
Xpathnavigator membernode = getmembernode (reflectedparameterdescriptor. actiondescriptor );
If (membernode! = NULL)
{
String parametername = reflectedparameterdescriptor. parameterinfo. Name;
Xpathnavigator parameternode = membernode. selectsinglenode (string. Format ("Param [@ name = '{0}']", parametername ));
If (parameternode! = NULL)
{
Return parameternode. value. Trim ();
}
}
}
Return "no documentation found .";
}
Public Virtual string getdocumentation (httpactiondescriptor actiondescriptor)
{
Xpathnavigator membernode = getmembernode (actiondescriptor );
If (membernode! = NULL)
{
Xpathnavigator summarynode = membernode. selectsinglenode ("summary ");
If (summarynode! = NULL)
{
Return summarynode. value. Trim ();
}
}
Return "no documentation found .";
}
Private xpathnavigator getmembernode (httpactiondescriptor actiondescriptor)
{
Reflectedhttpactiondescriptor reflectedactiondescriptor = actiondescriptor as reflectedhttpactiondescriptor;
If (reflectedactiondescriptor! = NULL)
{
String selectexpression = string. Format (_ methodexpression, getmembername (reflectedactiondescriptor. methodinfo ));
Xpathnavigator node = _ documentnavigator. selectsinglenode (selectexpression );
If (node! = NULL)
{
Return node;
}
}
Return NULL;
}
Private Static string getmembername (methodinfo method)
{
String name = string. Format ("{0}. {1}", method. declaringtype. fullname, method. Name );
VaR parameters = method. getparameters ();
If (parameters. length! = 0)
{
String [] parametertypenames = parameters. Select (Param => processtypename (Param. parametertype. fullname). toarray ();
Name + = string. Format ("({0})", String. Join (",", parametertypenames ));
}
Return name;
}
Private Static string processtypename (string typename)
{
// Handle nullable
VaR result = nullabletypenameregex. Match (typename );
If (result. Success)
{
Return string. Format ("{0} {1}", result. Groups [1]. Value, result. Groups [2]. value );
}
Return typename;
}
}

Replace the idocumentationprovider service with our custom service in application_start.

VaR Config = globalconfiguration. configuration;
Config. Services. Replace (typeof (idocumentationprovider), new xmlcommentdocumentationprovider (httpcontext. Current. server. mappath ("~ /App_data/mvcapplication2.xml ")));

There is an apipolicersettingsattribute that can control whether the API appears on the help page:

/// <Summary>
/// Delete API/values/5
/// </Summary>
/// <Param name = "ID"> </param>
[Apipolicersettings (ignoreapi = true)]
Public void Delete (int id)
{
}

You can also control whether the entire apicontroller document is published. You only need to apply apipolicersettingsattribute at the class level.

 [ApiExplorerSettings(IgnoreApi = true)]

 public class MySpecialController : ApiController

 { 

Through the iapiexplorer API, we can make great documents for our web API, and the interface design is scalable. You can create a web page or a helpcontroller. We recommend that You encapsulate it into a helpcontroller so that you can adapt to the web host or self host of webapi.

Part 1: Basic Help Page customizations

Changing the Help Page URI

Providing API documentations

Customizing the view

Part 2: providing custom samples on the Help Page

Setting custom sample objects

Setting the samples when the action returns an httpresponsemessage

Part 3: Advanced Help Page customizations

Adding additional information to the helppageapimodel

Creating new sample display templates

Making ASP. NET web API help page work on self-Hosted Services

Extending web API help page with information from attributes

Using curl to post request into ASP. NET web API Service