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

前言碎语

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

动手实践

我这里安装的是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/v1/swagger.json". 这样能够看到Swagger 生成的Json文件. 我们再来看看Swagger的UI.

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

另外, 如果想要增加一些描述也很简单. 只需调用下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文件并勾选, 如下图.

再加入一点代码.

        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加入注释.

运行一下看看效果.

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

--------------------------华丽丽的分割-----------------------------------

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