Use swagger to implement online api documentation for web APIs.

Use swagger to implement online api documentation for web APIs.

I. Preface

Our project usually contains many external interfaces, which need to be documented. The standard interface Description document needs to describe the interface address, parameters, return values, and remarks; as we used to write in word/excel, it is usually divided by modules. For example, if a module contains n interfaces, a document is formed and then managed by version control. The disadvantage of doing so is:

1. Not intuitive enough. It is troublesome to open the document View Interface every time.

2. Difficult document Maintenance

3. If the caller and tester are in trouble, you need to first find the interface and test it with the corresponding tool (for example, you may need to install the plug-in the browser)

We hope that we can directly browse it online and then test it in a browser. The detailed descriptions of interfaces are all completed with annotations in the program. Swagger can do this (ps seems that many developers do not know about this ...).

Ii. Use Swagger

  Swagger is a restful api documentation automatically generated online + function testing software.

Using swagger in web APIs can be very simple. You do not need to write any code and rely entirely on plug-ins. The procedure is as follows:

1. Create a web api Project

2. Use nuget to add a Swashbuckle package

3. Complete

That's all! Run the project. Go to http: // localhost: 57700/swagger/ui/index and you will see the following page. This is the default added two apicontrollers:

At this time, the interface does not have specific descriptions. For example, we add a comment description to ValuesController. Get, which is not displayed on the page. Follow these steps:

1. locate the location of 100 rows in SwaggerConfig under app_start. // c. includeXmlComments (GetXmlCommentsPath (); the following comment is changed to: c. includeXmlComments (GetXmlCommentsPath (thisAssembly. getName (). name); (Note that the comment is removed)

2. Add a method code in SwaggerConfig:

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

3. Modify the project generation. You can see the specific description document in the xml file corresponding to the bin, as shown below:

To regenerate a project, you must see the complete interface description. For example, we have a TestController in mind 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" > age < / 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 interface description. Click Try it out to call it:

Iii. Non-dependent code

The above method depends on the Swashbuckle package, which already contains the Swagger-UI component. We need to introduce this package in our code. In fact, we do not need to introduce it into the project. We need to deploy Swagger separately, including Swagger-Ui (api display) and Swagger-Editor (online Editor ), it depends on the nodejs environment, so you need to follow nodejs first. Deployment is actually 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 copy it to the specified directory. This deployment is also very simple. For details, refer:

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

Writing, commenting, and standardization documents of standardized APIs greatly improve the development efficiency of the team and facilitate project maintenance. For example, after using the online interface documentation, the tester only needs to enter parameters on the page and click "call" to view the call results.

Swagger also has an online version and does not need to be deployed on its own. In fact, the method of non-code dependency is more troublesome. The method of code dependency can be described in the program just like we write comments at ordinary times, so that developers can understand interface functions, it can also be displayed online and called by the release caller and tester.