神刀安全网

[Swagger]Asp.net core 中为API添加可视化工具


前言碎语

Swagger大名已经听闻很久了,可惜项目中一直没有机会用到。话说之前项目中一直用asp.net mvc 的help page, 用习惯了, 而且够用, 也就没有考虑新的东西。但是貌似现在对dotnet core没有支持,正好给我个借口,在一个即将开始的新项目,大胆尝试下Swagger. 写下这篇Blog还有一个原因. 起初我在找相关资料的时候, 要么是Asp.net 使用Swagger, 要么是dotnet core早期使用project.json的版本. 既然project.json已死, 我们就来看看最新的使用方式吧.

[Swagger]Asp.net core 中为API添加可视化工具

动手实践

我这里安装的是VS2017, 当然 VS Code也是可以的. 有了环境自然就可以开搞(Lu). Nuget安装Swagger的命令是:

Install-Package Swashbuckle.AspNetCore -Pre

我尝试了几个都不对, 感觉这个应该是预览版, 大家先用着, 以后有正式版出来我及时更新.
基于asp.net core的中间件机制, Swagger也需要加入到中间件服务的列表中, 这样才可以启用Swagger. 代码如下.

    // This method gets called by the runtime. Use this method to add services to the container.     public void ConfigureServices(IServiceCollection services)     {         // Add framework services.         services.AddMvc();          // Add Swagger UI.         services.AddSwaggerGen(c =>         {             c.SwaggerDoc("v1", new Info { Title = "DemoAPI", Version = "v1" });         });     }

然后启用Swagger, 生成相应的Json 文件, 并且指定Endpoint.

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)     {         loggerFactory.AddConsole(Configuration.GetSection("Logging"));         loggerFactory.AddDebug();          //app.UseMvc();         app.UseMvcWithDefaultRoute();          app.UseSwagger();          app.UseSwaggerUI(c =>         {             c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");         });     }

这样我们就可以运行起来看看.

[Swagger]Asp.net core 中为API添加可视化工具

访问地址就像前面代码中设置的一样 “/swagger/v1/swagger.json”. 这样能够看到Swagger 生成的Json文件. 我们再来看看Swagger的UI.

[Swagger]Asp.net core 中为API添加可视化工具

界面很简洁, 使用起来也很简单.

另外, 如果想要增加一些描述也很简单. 只需调用下SwaggerDoc函数, 代码如下.

services.AddSwaggerGen(c => {     c.SwaggerDoc("v1", new Info     {         Version = "v1",         Title = "DemoAPI",         Description = "A simple example ASP.NET Core Web API",         TermsOfService = "None",         Contact = new Contact { Name = "春上川酷", Email = "", Url = "http://www.jianshu.com/u/760d62bd90d5"},         License = new License { Name = "Use under LICX", Url = "http://url.com" }     }); });

如果想使用代码中的注释对API进行描述, 只需要配置XML文件即可. 方法很简单, 打开项目的属性, 找到XML文件并勾选, 如下图.

[Swagger]Asp.net core 中为API添加可视化工具

再加入一点代码.

        services.AddSwaggerGen(c =>         {             c.SwaggerDoc("v1", new Info             {                 Version = "v1",                 Title = "DemoAPI",                 Description = "A simple example ASP.NET Core Web API",                 TermsOfService = "None",                 Contact = new Contact { Name = "春上川酷", Email = "", Url = "http://www.jianshu.com/u/760d62bd90d5" },                 License = new License { Name = "Use under LICX", Url = "http://url.com" }             });              var basePath = PlatformServices.Default.Application.ApplicationBasePath;             var xmlPath = Path.Combine(basePath, "DemoAPI.xml");             c.IncludeXmlComments(xmlPath);         });

然后为一个API加入注释.

[Swagger]Asp.net core 中为API添加可视化工具

运行一下看看效果.

[Swagger]Asp.net core 中为API添加可视化工具

就是这样, 妈妈再也不用担心我的API不好调试了.

[Swagger]Asp.net core 中为API添加可视化工具

————————–华丽丽的分割———————————–

愿dotnet社区日益强大, 愿dotnet生态日趋完善. dotnet core技术交流群欢迎你, 扫描下面二维码进群.

[Swagger]Asp.net core 中为API添加可视化工具

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » [Swagger]Asp.net core 中为API添加可视化工具

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址