@model HelpDemo.Models.ApiModel @{viewbag.title = "API help";} @section Scripts {@Scripts. Render ("~/bundle S/jqueryui ") <script type=" Text/javascript ">//Apply jQuery accordion widget. Use the collapsible part of jquery $ (function () {$ (". Accordion"). accordion ();}); </script>} <div id= "Body" class= "Content-wrapper" >
If you run the application and navigate to/home/help, it should look similar to the following:
If you run this application and navigate to/home/help, the page looks similar (see figure 2-28):
Figure 2-28. help Page appearance
Adding a documentation Provider
Add a document Provider
You can provide documentation for your APIs by implementing the Idocumentationprovider interface. Documentation strings can come from any source. For this example, we'll define custom attributes that can is applied to the controller. The documentation provider would grab documentation strings from the attributes.
By implementing the Idocumentationprovider interface, you can provide documentation for the API. A document string (a string used as the content of a document-the translator's note) can be any resource you like (these resources are of course something about an API, such as a description of the API's role or meaning, what parameters, the types of these parameters and their effects, etc.-the translator's note). For this example, we will define some custom annotation properties that can be applied to the controller. The document provider captures the document string based on these annotation properties (gets information about the API based on the annotation properties and feeds the content into the document string for display in the help page-the translator's note).
For another approach, see Yao Huang Lin's blog post generating a Web API help page using Apiexplorer. He shows a documentation provider that pulls from XML documentation comments.
Another way to see Yao Huang Lin's blog post is "Generating a Web API help page using Apiexplorer (Generate a Web API with Apiexplorer)". He demonstrated a document provider that was collected from XML document annotations.
Here is the custom attributes:
The following are the custom annotation properties:
[AttributeUsage (AttributeTargets.Method)] public class Apidocattribute:attribute {public Apidocattribute ( String doc) { documentation = DOC; } public string Documentation {get; set;}} [AttributeUsage (AttributeTargets.Method)] public class Apiparameterdocattribute:attribute {public Apiparameterdocattribute (string param, string doc) { Parameter = param; documentation = DOC; } public string Parameter {get; set;} public string Documentation {get; set;}}
Here are a controller method with the attributes:
The following is a controller method that uses these annotation properties:
[Apidoc ("Gets a product by ID.")] [Apiparameterdoc ("id", "The ID of the product.")] Public httpresponsemessage Get (int id) { //...}
Now add a class that implements Idocumentationprovider.
Now, add a class that implements Idocumentationprovider :
public class Docprovider:idocumentationprovider {public string getdocumentation (Httpparameterdescriptor parame Terdescriptor) {String doc = ""; var attr = Parameterdescriptor.actiondescriptor. Getcustomattributes<apiparameterdocattribute> (). Where (p = = P.parameter = = parameterdescriptor.parametername). FirstOrDefault (); if (attr! = null) {doc = attr. documentation; } return doc; public string getdocumentation (Httpactiondescriptor actiondescriptor) {string doc = ""; var attr = actiondescriptor.getcustomattributes<apidocattribute> (). FirstOrDefault (); if (attr! = null) {doc = attr. documentation; } return doc; } }
Open the Global.asax.cs file and add the following code to the Application_Start method:
Open the Global.asax.cs file, and add the following code to the Application_Start method:
GlobalConfiguration.Configuration.Services.Replace ( typeof (Idocumentationprovider), New Docprovider ());
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. The MVC view can access them as follows:
Apiexplorer automatically calls the Idocumentationprovider interface to get the document string for each API. Store them in the documentation property of the apidescription and apiparameterdescription objects. MVC accesses them in the following way, depending on the image:
@foreach (Var api in Group) {
Now if you render the view, it shows the documentation strings:
Now, when the view is rendered, the document string is displayed (see Figure 2-29):
Figure 2-29. Help page showing the document string
Providing Sample Response bodies
Provides an example response body
One thing that's missing from our help page is examples of the HTTP response body. The Apiexplorer class does not provide any direct support for this. However, it does give the return type for each action. If the action returns a POCO, we can use this information to create a example response body, as follows:
One of the missing items from the help page above is an example of the HTTP response body. The Apiexplorer class does not provide any direct support for this. However, it can provide you with a return type for each action. If the action returns a Poco, we can use this information to create an example response body with the following steps:
1.
- Look up an example instance of the POCO.
Find an instance of Poco example. 2.
- Use a Media-type formatter to serialize the example instance.
Use a media type formatter to serialize this example instance. 3.
- Display the result as a string.
Displays the result as a string.
To see how this can work, add the following code to the Apimodel class:
To understand how to do this, add the following code to the Apimodel class:
Example instances//Example static product[] _products = new product[] {new Product () {Name = "Gizmo", Price = 1.05M }, New Product () {Name = "Gizmo2", Price = 0.995M}}; look-up table based on data type. Query table Dictionary<type based on data type, object> _sampledata = new Dictionary<type, object> () {{typeof (Product), _PR Oducts[0]}, {typeof (Ienumerable<product>), _products}}; Type Getresponsetype (Httpactiondescriptor action) {return action. ReturnType; public string Getsampleresponsebody (Apidescription API, String mediatype) {string BODY = null; Type returntype = Getresponsetype (API. Actiondescriptor); Object o; if (returntype! = null && _sampledata.trygetvalue (returntype, out O)) {var formatters = API. Supportedresponseformatters; Mediatypeformatter formatter = formatters. FirstOrDefault (f = f.supportedmediatypes.any (M = M.mediatype = = mediatype)); if (formatter! = NULL) {var content = new Objectcontent (ReturnType, O, formatter); BODY = content. Readasstringasync (). Result; }} return body; }
ADD the following code to the MVC view:
Add the following code to the MVC view:
@{ String response = @Model. Getsampleresponsebody (API, "Application/json"); } @if (response! = null) { <p>sample response body:</p> <p><code>@ Model.getsampleresponsebody (API, "Application/json") </code></p> }
Here are the resulting help page:
The following is the result of the help page (see Figure 2-30):
Figure 2-30. The help page for the example is displayed
This approach was not perfect. If an action returns a httpresponsemessage, there is no-deduce the format of the message body from the St atic API description. The same is true for a action that returns Loosely-structure JSON (see Anonymous and weakly-typed Objects).
This approach is not perfect. If an action returns Httpresponsemessage, there is no way to infer the format of the message body based on the static API description. Similarly, the action of returning the loosely structured JSON is the same (see Anonymous and weakly-typed Objects (anonymous and weakly typed objects)-6th chapter of this tutorial series).
The one-to-work around-problem is-to-use the API-ID to-look-up the response type. The API ID is a concatenation of the HTTP method and the relative URI path (for example, "Getapi/products/{id}").
One way to solve this problem is to use the API ID to find the response body type. The API ID is a concatenation of the HTTP method with the relative URI path (for example, "Getapi/products/{id}").
Response Types//Response type static dictionary<string, type> _responsetypes = new dictionary<string, type> () { {@ "Getapi/products/{id}", typeof (Product)} }; Type Getresponsetype (Apidescription API) { type T; if (_responsetypes.trygetvalue (api.id, Out T)) { return t; } Return API. Actiondescriptor.returntype; }
Custom attributes is another option.
Custom annotation properties are another option (for this issue).
Excluding an API
Exclude an API
To hide a API from the apiexplorer, add the apiexplorersettings attribute to the action and set IGN Oreapi to True.
In order to hide an API from apiexplorer , add the apiexplorersettings annotation attribute to the action and set Ignoreapi to true:
[Apiexplorersettings (Ignoreapi=true)] public httpresponsemessage Get (int id) {}
You can also add this attribute to the controller and to exclude the entire controller.
You can also add this annotation attribute to the controller to exclude the entire controller (all APIs).
Read this article if you feel something rewarding, please give a recommendation
ASP. NET Web API tutorial 2.4 Creating a Help page for the Web API