I play like this. Web Api (i): help page or User manual (Microsoft and Swashbuckle helps page)

Objective

Do you need to write API call manuals for your customers? Do you need to test your API interface? Do you need to interface with the front end? Then this article should be able to help you. This article describes two ways to create a Web Api Help document page, Microsoft helps page, and Swashbuckle.

Write a restful web Api

    /// <summary>    ///Stock Data Interface/// </summary>[Routeprefix ("Api/stocks")]     Public classStockscontroller:apicontroller {Private ReadOnlyList<stock>_stocks; /// <summary>        ///constructor Function/// </summary>         PublicStockscontroller () {_stocks=NewList<stock>            {                NewStock{symbol ="000001", Name ="Ping An bank", Exchange ="Shenzhen Securities Exchange"},                NewStock{symbol ="000002", Name ="Vanke a", Exchange ="Shenzhen Securities Exchange"},                NewStock{symbol ="000003", Name ="PT Gold Field a", Exchange ="Shenzhen Securities Exchange"},                NewStock{symbol ="000004", Name ="National Agricultural Science and Technology", Exchange ="Shenzhen Securities Exchange"},                NewStock{symbol ="000005", Name ="Century star Source", Exchange ="Shenzhen Securities Exchange"}            }; }        /// <summary>        ///Get stock List/// </summary>        /// <returns>Stock List</returns>[HttpGet] PublicIenumerable<stock>List () {return_stocks; }        /// <summary>        ///get the specified stock/// </summary>        /// <param name= "symbol" >Stock Code</param>        /// <returns>Specify Stock</returns>[HttpGet (), Route ("{symbol}", Name ="Get")]         PublicIhttpactionresult Get (stringsymbol) {            varStock = _stocks. Singleordefault (n = n.symbol = =symbol); if(Stock = =NULL)            {                returnNotFound (); }            returnOk (stock); }        /// <summary>        ///Add a stock/// </summary>        /// <param name= "Stock" >Stock Information</param>[HttpPost] PublicIhttpactionresult Create (stock stock) {returnCreatedatroute ("Get",New{symbol =stock.        Symbol}, stock); }        /// <summary>        ///Update a stock/// </summary>        /// <param name= "Stock" >Stock Information</param>[Httpput] PublicIhttpactionresult Update (stock stock) {if(_stocks. All (n = n.symbol! =stock. Symbol)) {returnNotFound (); }            returnStatusCode (httpstatuscode.nocontent); }        /// <summary>        ///partially update a stock/// </summary>        /// <param name= "symbol" >Stock Code</param>        /// <param name= "form" >stock information that needs to be updated</param>[Httppatch, Route ("{symbol}")]         PublicIhttpactionresult Partialupdate (stringsymbol, Partialform form) {            if(_stocks. All (n = n.symbol! =symbol)) {                returnNotFound (); }            returnStatusCode (httpstatuscode.nocontent); }        /// <summary>        ///Delete a stock/// </summary>        /// <param name= "symbol" >Stock Code</param>        /// <returns>whether to delete the success</returns>[Httpdelete, Route ("{symbol}")]         PublicIhttpactionresult Delete (stringsymbol) {            if(_stocks. All (n = n.symbol! =symbol)) {                returnNotFound (); }            returnOk (true); }        /// <summary>        ///This method does not display to the help page/// </summary>[HttpGet, Route ("Hide")] [Apiexplorersettings (Ignoreapi=true)]         Public voidnotshow () {}}

View Code

Microsoft Help Page

1. Add the Help page component to NuGet.

　　

After the component is added, the help page is automatically generated, in the file existence area (areas)

　　

2. Registration Area (areas)

Add the following code to the Application_Start () method in the Global.asax file:

Arearegistration.registerallareas ();

　　

Browse the generated help page: Http://localhost:xxxx/help

　　

A list of methods for the Web API has been shown, but the description of the method is still the default description.

3. Modify the configuration file generation location
Right-click the Project property to specify the output XML.

　　

Modify the XML path specified in the Register method in Areas\helppage\app_start\helppageconfig.cs to the path of the specified output above.

　　

　　

Review the help page again, and the method description is consistent with the code comment.

　　

Note: This can be used to update the English entry of the corresponding page in area to Chinese, of course, the style can also be adjusted.

4. Adding Test tools

Add the test client component to NuGet.

　　

Add the following code to areas\helppage\views\help\api.cshtml:

@Html. Displayformodel ("Testclientdialogs")

@section Scripts {

<link type= "Text/css" href= "~/areas/helppage/helppage.css" rel= "stylesheet"/>

@Html. Displayformodel ("Testclientreferences")

}

　　

Run the help page again, and one more Test button in the lower-right corner of each API description page.

4. Reference

Http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages

Swashbuckle Help Page

1. Add the Swashbuckle component to NuGet.

Then you can browse the generated help page: Http://localhost:xxxx/swagger

　　

A list of methods for the Web API has been shown, but the description of the method is not yet displayed.

2. Modify the configuration file generation location
Right-click the Project property to specify the output XML.

　　

Find SwaggerConfig.cs

　　

Remove the notes from the C.includexmlcomments (Getxmlcommentspath ())

　　

Implement the Getxmlcommentspath () method, specifying the path of the XML path to the specified output above.

　　

Review the help page again, and the method description is consistent with the code comment.

　　

2. Common exceptions

When using NuGet to refer to a DLL, it adds dependency information to the config, but occasionally does not add, which appears could not load file or assembly ' XXX ' or one of the its dependencies. The located assembly ' s manifest definition does not match the assembly reference. (Exception from hresult:0x80131040) exception.

Just add the corresponding dependency in config.

　　

4. Help page entry and style adjustment

If you want to modify or edit Swashbuckle help page styles or terms, you need to edit SwaggerConfig.cs, which may be a bit more complicated than Microsoft help page (I only changed Microsoft's, Did not mend the Swashbuckle). Details of how to modify can be consulted: Https://github.com/domaindrivendev/Swashbuckle

Brief summary

Swashbuckle help page is relatively simple to set up, but the style (with swagger logo) and the entry modification will be more cumbersome, so it is more appropriate to call the test as an internal interface specification for several interfaces.

Microsoft help page is relatively cumbersome to build, but style and entry modifications are a little easier, so it is more appropriate to use the document as an external interface call.

SOURCE download

Https://github.com/ErikXu/WebApi.HelpPage

I play like this. Web Api (i): help page or User manual (Microsoft and Swashbuckle helps page)