Implementing Web API online interface documentation using swagger

First, preface

Usually our project will contain many external interfaces, these interfaces need to be documented, the standard interface description document needs to describe the interface address, parameters, return values, notes and so on; as we have done before, it is written in Word/excel, usually by module, for example, a module contains n interfaces, Form a document and then manage it with version control. The disadvantages of doing this are:

1. Not intuitive, it's a hassle to open the document viewing interface every time

2. Document maintenance is difficult

3. The caller and tester are in trouble and need to find the interface first, testing with the appropriate tools (e.g. using a browser and possibly installing a plugin)

We want to be able to browse directly online and then test directly with the browser. The detailed description of the interface is done with annotations in the program. Swagger can do this work (PS as if many developers have not yet known this thing ...) ）。

Second, the use of swagger

　　Swagger is a restful interface document online automatic generation + functional test function software.

The use of swagger in the Web API can be said to be very simple, no need to write any code, completely dependent on the plug-in. The steps are as follows:

1. Create a new Web API project

　　

2. Add a Swashbuckle package using NuGet

　　

3. Complete

Yes, it's that simple! To run the project, go to address http://localhost:57700/swagger/ui/index to see the following page, which is the two Apicontroller added by default:

At this time the interface does not have a specific description of the information, for example, we add a comment description to Valuescontroller.get, on the page is still not displayed. you need to follow these steps:

1. Find//c.includexmlcomments (Getxmlcommentspath ()) in the position of swaggerconfig large 100 lines under App_start; The following note, instead: C. Includexmlcomments (Getxmlcommentspath (Thisassembly.getname (). Name)); ( Notice that the comment is removed )

2. Add a method code to Swaggerconfig:

        protected static string Getxmlcommentspath (string name)        {            return string. Format (@ "{0}\bin\{1}. XML ", AppDomain.CurrentDomain.BaseDirectory, name);        }

3. Modify the project generation, the corresponding XML file under the bin can see the specific description document, as follows:

　　

Rebuild the project and you will see the complete interface description. For example in our hearts a TestController is as follows:

    <summary>///test controller///    </summary> public    class Testcontroller:apicontroller    {        <summary>/        //Test Get Method        ///</summary>//<remarks> Test Get method </remarks>        // /<returns></returns>        [HttpGet] public        string Get ()        {            return "get";        }        <summary>///Test Post Method///</summary>//        <param name= "name" > Name </param> //        <param name= "Age" > Ages </param>//        <remarks> Test Post method </remarks>//        < Returns></returns>        [HttpPost] public        string Post (string name, int age)        {            return name + Age. ToString ();        }    }

The generated page is as follows, you can see the description of the interface, click Try it out to invoke:

　　

Third, non-dependent code

The above method relies on the Swashbuckle package, which already contains the Swagger-ui component. Our code needs to introduce this package, and in fact it doesn't need to be introduced in the project, it can be deployed separately Swagger, including Swagger-ui (API presentation) and Swagger-editor (online editor), it needs to rely on NODEJS environment, so we need to follow Nodejs first. Deployment is also very simple, for example, this is the result of my deployment:

Swagger-editor:

Swagger-ui:

After editing, you only need to save the file as a JSON file and then copy it to the specified directory. This deployment is also very simple and can be referenced as follows:

1.http://www.raye.wang/2016/09/29/swaggerhuan-jing-da-jian-zhi-fei-yi-lai-dai-ma-fa/?utm_source=tuicool& Utm_medium=referral

2.http://blog.csdn.net/ron03129596/article/details/53559803

Iv. Summary

The compilation and annotation of the normalized API, as well as the standardized documentation, have greatly improved the team's development efficiency and also facilitated the maintenance of the project. For example, after using the online interface documentation, the tester will only need to enter parameters in the page and click on the call to see the result.

Swagger also has an online version and does not need to be deployed on its own. In fact, the way of non-code dependencies is more cumbersome, the use of code-dependent methods can be as often as we write comments, can be described in the program, easy for developers to understand the interface function, can also be displayed online, release callers and testers call.

Implementing Web API online interface documentation using swagger