[Practical Production of web api projects]-interface documentation and online testing (2)

[Practical Production of web api projects]-interface documentation and online testing (2)

Previous Article: [web api Project Practice Series]-Introduction to Web API 2 (1)

This document describes how to help API callers with API functions, input parameters, and output parameters, and online API testing (this is also convenient for our own development and debugging)

Let's first take a look at the final results of our API help documentation and online testing:

Overview

[RoutePrefix ("api/products")] public class ProductController: apiController {/// <summary> /// obtain the product page data /// </summary> /// <returns> </returns> [HttpGet, route ("product/getList")] public Page <Product> GetProductList () {throw new NotImplementedException ();} /// <summary> /// obtain a single product /// </summary> /// <param name = "productId"> </param> /// <returns> </returns> [HttpGet, route ("product/get")] public Product GetProduct (Guid productId) {throw new NotImplementedException ();} /// <summary> /// add product /// </summary> /// <param name = "product"> </param> /// <returns> </returns> [HttpPost, route ("product/add")] public Guid AddProduct (Product product) {throw new NotImplementedException ();} /// <summary> /// update the product /// </summary> /// <param name = "productId"> </param> /// <param name = "product"> </param> [HttpPost, route ("product/update")] public void UpdateProduct (Guid productId, Product product) {throw new NotImplementedException ();} /// <summary> /// Delete the product /// </summary> /// <param name = "productId"> </param> [HttpDelete, route ("product/delete")] public void DeleteProduct (Guid productId) {throw new NotImplementedException ();}}

All the api help information displayed in us is extracted from our annotation information, so the API annotation information here is essential.

 

Add the Swagger. Net component (the custom version has not been updated officially for many years and can only be updated by yourself)

Add Swagger to the project. net component. As this version has been updated a lot in the official version, directly copy the code from the project (if necessary, it can be used after the Nuget component is released)

To add Swagger. NET, follow these steps:

1. Introduce Swagger. Net Project in the Project.

2. Add SwaggerNet. cs under App_Start of the Web API Project

The Code is as follows:

[assembly: WebActivatorEx.PreApplicationStartMethod(typeof(SwaggerNet), "PreStart")]
[assembly: WebActivatorEx.PostApplicationStartMethod(typeof(SwaggerNet), "PostStart")]
namespace Niusys.WebAPI.App_Start
{
    public static class SwaggerNet
    {
        public static void PreStart()
        {
            RouteTable.Routes.MapHttpRoute(
                name: "SwaggerApi",
                routeTemplate: "api/docs/{controller}/{action}",
                defaults: new { swagger = true }
            );
        }

        public static void PostStart()
        {
            var config = GlobalConfiguration.Configuration;
            config.Filters.Add(new SwaggerActionFilter());
        }
    }
}

It is mainly used to register api documentation Request Routing and intercept documentation requests.

3. Copy the SwaggerUI folder in the WebAPI project. Here is the page for the help document to process files.

4. enable XML document generation for WebAPI Projects

 

In this case, you can start the project and enter the swaggerui (http: // localhost: 14527/swaggerui/) directory in the URL to access our API help documentation system and perform online testing.

 

Summary:

The principle of this help document is implemented through the XML annotation in the Code. The principle is that when the api/doc is requested, in this case, retrieve the xml help document corresponding to the controler/action and display it later.

Its test is completely done using its internal crazy jQuery Ajax, which is highly integrated with the interface to fully meet the needs of our project.

 

This code: Download the code