Using swagger to provide API documentation on the Core WEB API

When I developed my own blogging system (http://daxnet.me), I added swagger-based API documentation capabilities to my RESTful services. After setting the default boot route for iisexpress to the Swagger API documentation page, it is convenient to automatically redirect to the API documentation page after iisexpress launches the Web API site. This not only allows me to quickly check the rationality of API design, but also from the perspective of the use of the API for my own convenience. Is the swagger document interface of my blog system RESTful API:

Next, let's take a look at how to implement this swagger-based API documentation page on the ASP. NET Core Web API.

Implementation steps to create an ASP. NET WEB API application

This is not much to say, there are many ways to create an ASP. NET core application using Visual Studio 2015 or 2017, after you have installed Visual Studio 2015/2017 Tools for. You can also use the dotnet new–t web command of the. NET Core SDK to create a new Web project under the current folder. The presentation of this article is based on Visual Studio 2015.

Add a reference to the Swashbuckle.swaggerui and Swashbuckle.swaggergen libraries

1. Right-click on the Web API project and select Manage NuGet Packages:
   
   
2. In the Visual Studio nuget tab, under Browse tab, enter Swashbuckle.swaggerui, and remember to check the "Include prerelease" option:
   
   
3. Packages selected in the installation into the project
4. Install the Swashbuckle.swaggergen package into the project in the same way as above

Note: Currently two packages are still in beta version, so the option to include prerelease is checked.

Open the XML document feature

1. Right-click on the Web API project and select the Properties option:
   
   
2. In the Project Properties tab, switch to the build page while opening the XML documentation file option:
   
   
3. The XML document for the Web API project code is generated. As a result, compiling your project generates a series of warning messages because you have not yet completed the documentation comments for the Code

Modify the Startup.cs file

2. Double-click Open Startup.cs File
3. In the Configureservices method, add the following code to increase support for swagger:
   

   1234567891011121314151617181920

   publicvoid ConfigureServices(IServiceCollection services){    // Add framework services.    services.AddMvc();    services.AddSwaggerGen();    services.ConfigureSwaggerGen(options =>    {        options.SingleApiVersion(newSwashbuckle.Swagger.Model.Info        {            Version = "v1",            Title = "My Web Application",            Description = "RESTful API for My Web Application",            TermsOfService = "None"        });        options.IncludeXmlComments(Path.Combine(PlatformServices.Default.Application.ApplicationBasePath,             "WebApplication14.XML")); // 注意：此处替换成所生成的XML documentation的文件名。        options.DescribeAllEnumsAsStrings();    });}

4. In the Configure method, add the following code:
   

   12345678910

   public  void  configure (Iapplicationbuilder app, Ihostingenvironment env, iloggerfactory loggerfactory) {      loggerfactory.addconsole (configuration.getsection ( "Logging"      loggerfactory.adddebug ();       app. Useswagger ();      app. Useswaggerui ();       app. Usemvc ();

Modify Web API Project home page redirection

1. Expand the Properties node on the project, double-click the Launchsettings.json file
   
   
2. Modify the values of the Launchurl under different profiles as needed, such as in this case, modify the Launchurl under the IIS Express node to change the value in:
   
   
3. To test, in Visual Studio, set the Web API project as the startup item, and then directly ctrl+f5 the startup project, you will see the following screen:
   
   
4. Add some comments to the project try it? Open the ValuesController.cs file and add some comments:
   
   
5. Run the site again and discover that these document annotations are reflected in the API page:
   
   
6. We can also make the API call test directly in the API documentation page:
   

Summarize

This article describes how to add the Swagger API documentation page to the ASP. Swagger is a great restful API design, build, document, and normalization tool in walkthrough. It is based on the Yaml language and is available in the official Yaml language editor. Developers can use YAML to define the interface contract for the RESTful API through various editors, as well as to generate restful server and client-side code for dozens of programming languages (in the above, have you noticed the Swagger.json file URL in the green background title bar?). By downloading this file and then importing it into the official website's editor, you can download the service-side framework and the client calling code that contains our RESTful API implementation immediately, based on your development language. This is a bit like the WSDL in the era of SOAP Web services (Web Service Description Language) and tools such as Wsdl.exe, svcutil.exe, and so on. In addition to Swagger,raml is also a similar product, interested friends can go to their respective official website to understand.

Category:. NET Core

Using swagger to provide API documentation on the Core WEB API