循序渐进学.Net Core Web Api开发系列【2】：利用Swagger调试WebApi

系列目录

循序渐进学.Net Core Web Api开发系列目录

 本系列涉及到的源码下载地址：https://github.com/seabluescn/Blog_WebApi

 

一、概述

既然前后端开发完全分离，那么接口的测试和文档就显得非常重要，文档维护是一件比较麻烦的事情，特别是变更的文档，这时采用Swagger就会非常方便，同时解决了测试和接口文档两个问题。

 

二、使用NuGet获取包

使用NuGet搜索包：Swashbuckle.aspnetcore并安装。

 

三、添加代码

在Startup类的ConfigureServices方法内添加下面代码（加粗部分）

      public void ConfigureServices(IServiceCollection services)
        {
           services.AddMvc();
        <strong>services.AddSwaggerGen(option </strong></span><strong>=&gt;<span style="color: #000000;">
        {
            option.SwaggerDoc(</span><span style="color: #800000;">"</span><span style="color: #800000;">v1</span><span style="color: #800000;">"</span>, <span style="color: #0000ff;">new</span><span style="color: #000000;"> Info
            {
                Version </span>= <span style="color: #800000;">"</span><span style="color: #800000;">v1</span><span style="color: #800000;">"</span><span style="color: #000000;">,
                Title </span>= <span style="color: #800000;">"</span><span style="color: #800000;">SaleService接口文档</span><span style="color: #800000;">"</span><span style="color: #000000;">,
                Description </span>= <span style="color: #800000;">"</span><span style="color: #800000;">RESTful API for SaleService.</span><span style="color: #800000;">"</span><span style="color: #000000;">,
                TermsOfService </span>= <span style="color: #800000;">"</span><span style="color: #800000;">None</span><span style="color: #800000;">"</span><span style="color: #000000;">,
                Contact </span>= <span style="color: #0000ff;">new</span> Contact { Name = <span style="color: #800000;">"</span><span style="color: #800000;">seabluescn</span><span style="color: #800000;">"</span>, Email = <span style="color: #800000;">"</span><span style="color: #800000;">seabluescn@163.com</span><span style="color: #800000;">"</span>, Url = <span style="color: #800000;">""</span><span style="color: #000000;"> }
            });

            </span><span style="color: #008000;">//</span><span style="color: #008000;">Set the comments path for the swagger json and ui.</span>
            <span style="color: #0000ff;">var</span> basePath =<span style="color: #000000;"> PlatformServices.Default.Application.ApplicationBasePath;
            </span><span style="color: #0000ff;">var</span> xmlPath = Path.Combine(basePath, <span style="color: #800000;">"</span><span style="color: #800000;">SaleService.xml</span><span style="color: #800000;">"</span></strong><span style="color: #000000;"><strong>);
            option.IncludeXmlComments(xmlPath);
        });</strong>
    }</span></pre>

在Startup类的Configure方法内添加下面代码（加粗部分）

       public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {   
            app.UseMvcWithDefaultRoute();
        <strong>app.UseSwagger();
        app.UseSwaggerUI(option </strong></span><strong>=&gt;<span style="color: #000000;">
        {
            option.ShowExtensions();
            option.SwaggerEndpoint(</span><span style="color: #800000;">"</span><span style="color: #800000;">/swagger/v1/swagger.json</span><span style="color: #800000;">"</span>, <span style="color: #800000;">"</span><span style="color: #800000;">SaleService V1</span><span style="color: #800000;">"</span></strong><span style="color: #000000;"><strong>);
        });</strong>
    }</span></pre>

 

四、配置

需要在生成配置选项内勾选XML文档文件，项目编译时会生成该文件。Debug和Release模式都设置一下。否则会报一个System.IO.FileNotFoundException的错误。

 

五、启动

 启动项目，浏览器输入：http://localhost:50793/swagger/ 即可。

也可以修改launchsettings.json文件，默认项目启动时运行swagger

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

{   "iisSettings": {     "windowsAuthentication": false,     "anonymousAuthentication": true,     "iisExpress": {       "applicationUrl": "http://localhost:50792/",       "sslPort": 0     }   },   "profiles": {     "IIS Express": {       "commandName": "IISExpress",       "launchBrowser": true,       "launchUrl": "api/values",       "environmentVariables": {         "ASPNETCORE_ENVIRONMENT": "Development"       }     },     "SaleService": {       "commandName": "Project",       "launchBrowser": true,       "launchUrl": "swagger",       "environmentVariables": {         "ASPNETCORE_ENVIRONMENT": "Development"       },       "applicationUrl": "http://localhost:50793/"     }   }}

如果你对你的控制器方法进行了注释，swagger接口页面就会体现出来。

        /// <summary>
        /// 根据产品编号查询产品信息
        /// </summary>
        /// <param name="code">产品编码</param>
        /// <returns>产品信息</returns>
        [HttpGet("{code}")]  
        public Product GetProduct(String code)
        {
            var product = new Product
            {
                ProductCode = code,
                ProductName = "啫喱水"
            };
        </span><span style="color: #0000ff;">return</span><span style="color: #000000;"> product;
    }</span></pre>

 

下面为Swagger的首页：可以用它进行API的调试了。