Add automatic document functionality to dotnet Core Web API via Swashbukle

The DotNet Core WEB API provides developers with a good framework for developing restful APIs. So how do these API interfaces manage? Swagger is a good choice, swagger does not require the developer to maintain the interface documentation, as long as the developer's interface follows restful specifications, swagger will generate documentation based on the API interface.

For the front-end separation of the development model, the front-end developers will generally first define the interface, and then independently developed, the backend developers can use swagger quickly generate no business logic interface document, the interface returned to the mock Data, so that the front-end developers can start calling the interface earlier, As long as the Swagger interface document is concerned about whether there is a change, early detection errors, avoid the front and back end of the final integration, there is a big problem.

Back-end developers using swagger can also be very well debugged, Swagger provides a simple UI interface to simulate simple post,get,put. Features are not curl or postman powerful, but the advantage is simple and fast, as long as the Swagger document interface point can be.

Here are the following: Dotnet Core 2.0 below the Swashbukle.aspnetcore

GitHub Address: Https://github.com/domaindrivendev/Swashbuckle.AspNetCore

The source code of this article: Dotnet-core-sample in the Sample1

1. First create a dotnet core Web API project and enter it via the command line

dotnet New Webapi-name Sample1

2. Then download Swashbuckle Aspnetcore

dotnet Add Package Swashbuckle.aspnetcore

Under vs 2017, through the package management Console, Nuget Package Manager, tools, run

Install-package Swashbuckle.aspnetcore

Note: This is install-package swashbuckle.aspnetcore not install-package swashbuckle

3. In the Startup.cs file, introduce the Swashbuckle

using Swashbuckle.AspNetCore.Swagger;

　　

4. Register Swagger Generator in the Configureservice method in the Startup.cs file

         Public void configureservices (iservicecollection services)        {            services. Addmvc ();             = =            {                config. Swaggerdoc ("v1"new"My API" " v1 "  });            });        }

5. Adding swagger middleware to the Configure method

         Public void Configure (Iapplicationbuilder app, ihostingenvironment env)        {            if  (env. Isdevelopment ())            {                app. Usedeveloperexceptionpage ();            }            App. Usemvc ();            App. Useswagger ();        }

6. Finally execute the dotnet run or F5, you can run the project directly

Dotnet Run

By default, API interface documentation can be accessed via http://localhost:5000/swagger/

Note: To automatically generate the document, the interface under the controller must display the specified HTTP request mode, Post,get,put,delete

Once swagger is running, some simple configurations are sometimes required for the project:

In addition to the previously mentioned new info {Title = "My API", Version = "V1"},swashbukle can also be configured with additional information, as described in OPENAPI specification.

Config. Swaggerdoc ("v1",    NewInfo {Title="My api-v1", Version="v1", Description="A Sample API to demo Swashbuckle", Termsofservice="Knock yourself out", Contact=NewContact {Name="Joe Developer", Email="[email protected]"}, License=NewLicense {Name="Apache 2.0", the Url="http://www.apache.org/licenses/LICENSE-2.0.html"        }    })

Finally, if you want to configure multiple swagger documents, Need to notify add Swagger generator and endpoint

Config. Swaggerdoc ("v2"new"My api-v2""v2  "}"  ); config. Swaggerendpoint ("/swagger/v2/swagger.json""My API V2 ");

Add automatic document functionality to dotnet Core Web API through Swashbukle