Asp.netCore3.0 WebApi从0到1手摸手教你写【

2019-10-17 本文已影响0人我是Mr小赵先生

今天的任务是给我们写的接口增加一个swagger接口文档

第一步添加swagger包

打开程序包管理控制台，然后输入以下代码安装swagger包
Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4

安装swagger

经过测试，如果通过Nuget包管理器安装swagger只能安装4.0.1版本，但是这个版本尝试以后不支持.NetCore3.0，所以要按照上面的方法用命令行的方式安装Swashbuckle.AspNetCore5.0版本

image.png

安装完毕以后可以在包中看到Swashbuckle.AspNetCore5.0

image.png

第二步设置API输出XML文档文件

双击Properties，在打开的页面选择生成，按照红框内容配置xml文件输出

Properties

输出xml文档文件

第三步注册Swagger服务

打开XXX.api中Startup.cs文件，在ConfigureServices中注册Swagger服务

        // 用来向容器中注册服务,注册好的服务可以在其他地方进行调用
        public void ConfigureServices(IServiceCollection services)
        {
            //数据库连接字符串
            string conn = Configuration.GetConnectionString("xxxDB");
            Models.XXXEntities.xxxContext.ConStr = conn;
            
            //注册swagger服务,定义1个或者多个swagger文档
            services.AddSwaggerGen(s=> {
                //设置swagger文档相关信息
                s.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "xxxWebApi文档",
                    Description = "这是一个简单的NetCore WebApi项目",
                    Version = "v1.0"
                });
            
                //获取xml注释文件的目录
                var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = System.IO.Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 启用xml注释
                s.IncludeXmlComments(xmlPath);
            });
            services.AddControllers();
            services.AddRouting();
            //services.AddDbContext<Models.XXXEntities.xxxContext>(options =>
            //{
            //    options.UseSqlServer(conn);
            //});
        }

SwaggerDoc是配置Swagger文档相关属性的地方，比如名称、描述、版本等
IncludeXmlComments 设置第二步中xml文档文件路径

打开XXX.api中Startup.cs文件，在Configure中启用Swagger服务

        // 用来配置中间件管道,即如何响应http请求.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("api/Error");
            }
            app.UseRouting();

            app.UseAuthorization();
            //启用swagger中间件
            app.UseSwagger(opt=> {
                //opt.RouteTemplate = "api/{controller=Home}/{action=Index}/{id?}";
            });
            //启用SwaggerUI中间件（htlm css js等），定义swagger json 入口
            app.UseSwaggerUI(s => {
                
                s.SwaggerEndpoint("/swagger/v1/swagger.json", "xxxWebapi文档v1");

                //要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：
                //s.RoutePrefix = string.Empty;
            });
            app.UseEndpoints(endpoints =>
            {
                //endpoints.MapControllerRoute(
                //     name: "default",
                //     pattern: "api/{controller}/{action}/{id?}");
                endpoints.MapControllers();
            });
        }

如果想通过http://xxxx.com:<port>的方式访问Swagger文档则添加RoutePrefix = string.Empty;即可

如果使用目录及 IIS 或反向代理，请使用 ./前缀将 Swagger 终结点设置为相对路径。例如 ./swagger/v1/swagger.json。使用/swagger/v1/swagger.json 指示应用在 URL 的真实根目录中查找 JSON 文件（如果使用，加上路由前缀）。例如，请使用 http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json而不是http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json。

第四步解决No operations defined in spec!问题

一般来说按照上面的方式配置好就可以访问Swagger文档了，但是最后还是出了“No operations defined in spec!”的问题

No operations defined in spec!

问题原因：在前2个教程中我们将路由配置统一从Controller中去掉然后endpoints.MapControllerRoute设置了路由模版，由于Swagger无法在Controller中找到[Route("api/[controller]/[action]")]和[ApiController]从而触发了“No operations defined in spec!”的问题。下图是我们注释的内容和增加的内容

Controller中注释掉的路由模版
Startup.cs中增加的路由模版

解决方案
1.将Startup.cs中Configure里的路由模版注释掉，改成endpoints.MapControllers();然后在Controller里添加路由模版，此方法虽然可以解决问题，但是并不是最优的。

2.【最优方案】将Startup.cs中Configure里的路由模版注释掉，改成endpoints.MapControllers();，增加BaseController.cs并继承ControllerBase，然后在BaseController设置路由模版，让Controller继承BaseController。说的有点饶舌，看代码

BaseController.cs代码

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace XXX.api
{
    /// <summary>
    /// 自定义路由模版
    /// 用于解决swagger文档No operations defined in spec!问题
    /// </summary>
    [Route("api/[controller]/[action]")]
    [ApiController]
    public class BaseController : ControllerBase
    {
    }
}

UserController.cs代码

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace XXX.api.Controllers
{
    /// <summary>
    /// 用户接口
    /// </summary>
    //[Route("api/[controller]/[action]")]
    //[ApiController]
    public class UserController : BaseController
    {
        /// <summary>
        /// 测试接口
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public IActionResult Login()
        {
            return Ok("hello");
        }
        /// <summary>
        /// 增加一个用户
        /// </summary>
        /// <param name="model"></param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult AddUser([FromBody]Models.User.AddUserP model)
        {
            var r = Bo.UserBo.AddUser(model);
            return Ok(r);
        }
    }
}