ASP. NET core using swagger, you have to step on the pit

Tag: The GitHub is an entity get extra art. JSON disco

A long time not to write blog, changed the new job very tired, very busy. Daily normal overtime to 21 points, occasionally will go to the wee hours, overtime is very tired, but this period of time, also did learn a lot of knowledge, today this article and share with you: ASP. NET core using swagger, you have to step on the pit.

This article highlights several points:

• Swagger cross-layer annotation issues
• Swagger get requests to pass multiple parameter issues
• Swagger Enum Comment Issues
• Swagger API Documentation Version control

Step one: Build a WEBAPI project or MVC project to introduce swagger NuGet

I create a project, habitually create a solution first, named TB.AspNetCore.Swagger

Then will be in the solution to create a new project, named TB.AspNetCore.Swagger.SApi, and then choose Webapi,https Best to remove, plus after the prompt you want a certificate, will also remind you that the site is not safe, we do the test, no need to tick

For the purpose of this project, we will continue to TB.AspNetCore.Swagger.Data database entities, TB, in common three class library projects. AspNetCore.Swagger.Model Release Model-VIEWMODEL,TB. AspNetCore.Swagger.Enum enum type

Delete the default generated class and controller for the project, introduce the swagger NuGet package on the API project, search: Swashbuckle.aspnetcore, this package is constantly updated fast, it has reached 3.0

Part II: Introducing version Control NuGet, adding critical configuration code

These two packages are made version control management, if not required can not be added, here I do a demo to add on, Additional to introduce a package Microsoft.Extensions.PlatformAbstractions, this package is to get some system configuration Path variable package, this package is really chicken, no comment. Add some key code in the configuration and Configurationservice, the code is as follows:

Services. Addswaggergen (Options + =//Resolve the Iapiversiondescriptionprovi Der Service//Note:that we have to build a temporary service provider here because one had not been C Reated yet var Provider = Services. Buildserviceprovider ().                    Getrequiredservice<iapiversiondescriptionprovider> ();  Add a swagger document for each discovered API version//note:you might choose to skip or document Deprecated API versions differently foreach (var description in provider. apiversiondescriptions) {options. Swaggerdoc (description.                    GroupName, Createinfoforapiversion (description)); }//Add a custom operation filter which sets default values options.                    Operationfilter<swaggerdefaultvalues> (); IntegrateXML comments options.                    Includexmlcomments (Xmlcommentsfilepath); Options.                Includexmlcomments (Xmlmodelsfilepath);        });p ublic void Configure (Iapplicationbuilder app, Ihostingenvironment env, Iapiversiondescriptionprovider provider) {if (env. Isdevelopment ()) {app.            Usedeveloperexceptionpage (); } app.            Usemvc (); Swagger app.            Useswagger (); App. Useswaggerui (Options + {foreach (var description in provider). apiversiondescriptions) {options. Swaggerendpoint ($ "/swagger/{description. Groupname}/swagger.json ", description.                    Groupname.toupperinvariant ());        }                }); }

Part III: Create a new controller to test our project

I made an order query controller, a submit order, a query order, a query order for GET request multi-parameter, submit the order as a POST request, where the memo design to the enumeration type how to load

The code is as follows:

namespaceTB. aspnetcore.swagger.sapi.controllers{[Produces ("Application/json")] [Apiversion ("1.0", Deprecated =false)] [Route ("Api/v{api-version:apiversion}/[controller]/[action]")] [Apicontroller] Public classOrdercontroller:controllerbase {/// <summary>        ///Order Enquiry/// </summary>        /// <param name= "Ordercode" >Order Number</param>        /// <param name= "Ordername" >Order name</param>        /// <returns></returns>[HttpGet ("{Ordercode}/{ordername}")]         PublicOrdermodel Queryorder (stringOrdercode,stringordername) {Ordermodel Model=NewOrdermodel {Ordercode=Ordercode}; returnmodel; }        /// <summary>        ///Submit Order/// </summary>        /// <param name= "model" ></param>        /// <returns></returns>[HttpPost] PublicOrdermodel Suborder ([Frombody]ordermodel model) {returnmodel; }    }     Public classOrdermodel {/// <summary>        ///Order Number/// </summary>         Public stringOrdercode {Get;Set; } /// <summary>        ///Order Amount/// </summary>         Public decimalOrderAmount {Get;Set; } /// <summary>        ///Order type/// <Remark>        ///0 Merchants settled in///1 Offline Trading/// </Remark>        /// </summary>         PublicOrdertypeinfo OrderType {Get;Set; } }    /// <summary>    ///     /// </summary>     Public enumOrdertypeinfo {/// <summary>        ///Business Occupancy/// </summary>[Description ("Business Occupancy")] Storeentry=0,        /// <summary>        ///Offline Trading/// </summary>[Description ("Offline Trading")] Storetrade=1,    }}

as follows: * * I wrote the model and enum into a file, if the separate cross-layer write, there is no problem, just need to configure in the STARTP, because of the time, the source I uploaded to my github, no longer subdivided

GitHub Address: Https://github.com/TopGuo/TB.AspNetCore.Swagger

If you think this article is good or rewarding, you can click on the " recommend " button in the bottom right corner to support the spirit, as this support is the biggest motivation for me to continue writing and sharing.

You are welcome to pay attention to my public number, the number of public number of fans, that is, you love my degree!

ASP. NET core using swagger, you have to step on the pit