.NET core 怎么使用Swagger

.Net Core使用Swagger

随着技术的不断更新，现在的网站开发基本都是使用前后端分利的模式，这样式前端开发者和后端开发者只需要专注于自己擅长的即可。但是这时候有个问题，就是前后端需要通过API接口的方式调用关联，接口文档的好坏是决定开发进度的重要因素，像以前后端开发使用Word的形式提供接口文档，总会存在一些问题。前端抱怨接口文档与实际情况不一致。后端又觉得编写及维护接口文档费时费力，而Swagger刚好解决了这一问题

---

---

一、为什么使用Swagger

1. 广泛用于可视化API，使用Swagger UI为前端开发人员提供在线沙箱，无需再次编写API文档。
2. Swagger是用于生成RESTful Web服务的可视化表示的工具，规范和完整框架实现。
3. 内嵌调试，可以查看接口状态和返回值结果很方便

二、使用步骤

1.创建.NetCore项目（VS2019）

这里使用最新的ASP.NET Core 3.1创建WebAPI接口。
具体如下（示例）：




到这儿一个.NET core webapi就创建完成了。

2. ASP.Net Core使用Swagger

打开nuget包管理，选择浏览搜索Swashbuckle.AspNetCore进行安装：

然后依次点击确定和接受：


这个时候就已经安装完成了，项目依赖项里会多出一个包的引用。

首先打开Startup类，简单介绍下类中的方法ConfigureServices和Configure：
ConfigureServices方法是用于配置依赖注入以在运行时根据依赖关系创建对象，
而Configure是用于配置中间件（middleware）以构建请求处理流水线。
简单理解这两个方法的关系，好比在公司，ConfigureServices就是安排工作岗位人员，Configure就是来制定工作流程。

下面注册Swagger，我们先创建个类存放注册信息（目的是让代码更整洁，逻辑更清晰一点）

需要引用
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;


namespace Core.WebApi.ConfigureSwagger
{
    public static class ConfigureSwagger
    {
        public static void ConfigureSwaggerUp(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            //注册Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Title = "Swagger接口文档",
                    Version = "v1",
                    Description = $"Core.WebApi HTTP API V1",
                });
                c.OrderActionsBy(o => o.RelativePath);
            });
        }
    }
}

接下来到 Startup 类，找到ConfigureServices 注册我们写好的服务：
（记得引用前面添加的类）

public void ConfigureServices(IServiceCollection services)
{
	//注册Swagger服务
	services.AddSwaggerUp();
	services.AddControllers();
}

添加中间件：

我们把IIS 启动的注释，项目启动的Url改成根目录:

修改后按F5启动项目:
如果配置了 RoutePrefix 属性的值，启动就是这样子找不到了

接下来我们输入/api敲回车，就可以了，这就是配置 RoutePrefix 属性的作用。

接下来我们实际使用,创建一个BaseController继承ControllerBase ,自带的删除掉。
BaseController是一个基类，目的是为了自定义路由，然后放一些公共的方法，后面新建类就只需要继承BaseController类

接下来我们创建一个UserController，创建方式如同上面的，把这两个地方修改一下


添加代码，来个Hello World

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

namespace Core.WebApi.Controllers
{

    public class UserController : BaseController
    {
        [HttpGet]
        public IActionResult Hello()
        {
            return Ok("Hello World");
        }
    }
}

F5启动，这样一个基本的Swagger就已经搭建完成。

下面继续在Swagger下面添加一些东西。文档注释，我们新建一个Model类库，因为Swagger不仅可以把接口注释显示，也可以对实体进行注释的显示。
创建一个类库项目

右键项目->属性->生成 WebApi.Core.Model 也同样操作

配置好了XML，接下来要关联这个配置 编辑 SwaggerSetUp.cs类 找到 AddSwaggerSetup函数，添加XML关联代码

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using System.IO;

namespace Core.WebApi.ConfigureSwagger
{
    public static class ConfigureSwagger
    {
        public static void AddSwaggerUp(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            //注册Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Title = "Swagger接口文档",
                    Version = "v1",
                    Description = $"Core.WebApi HTTP API V1",
                });
                c.OrderActionsBy(o => o.RelativePath);

                // 获取xml注释文件的目录
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "Core.WebApi.Api.xml");
                c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
                // 获取xml注释文件的目录
                var xmlPathModel = Path.Combine(AppContext.BaseDirectory, "Core.WebApi.Model.xml");
                c.IncludeXmlComments(xmlPathModel , true);//默认的第二个参数是false，这个是controller的注释，记得修改
            });
        }
    }
}

下面在model类库中添加一个类UsersModel 写好全部的注释

接下来在UsersController 添加函数来验证 注释是否有效

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

namespace Core.WebApi.Controllers
{
    /// <summary>
    /// 用户控制器
    /// </summary>
    public class UserController : BaseController
    {
        /// <summary>
        /// 测试Hello World
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public IActionResult Hello()
        {
            return Ok("Hello World");
        }
    }
}

这里我们加了注释，启动F5 看看效果，从下面的图片看，是没问题的注释已经显示出来了，但是model在哪里，为什么没有显示出来

我们在UsersController 添加如下函数

/// <summary>
    /// 用户控制器
    /// </summary>
    public class UserController : BaseController
    {
        /// <summary>
        /// 测试Hello World
        /// </summary>
        /// <returns></returns>
        [HttpPost]
        public IActionResult UsersTestSwagger(UsersModel usersModel)
        {
            return Ok(usersModel);
        }
    }

然后F5启动，这里我们看到 model类 显示出来了

到此，.net core 搭建和使用Swagger就算完成了，是不是很简单。
下面在简单介绍一下，请求和响应应该怎么去看


我们编辑好参数，单击Execute按钮，可以看到请求一个json串，并且把这个json串原样输出了，这在以前需要借助工具来完成，现在直接在启动的程序上就可以查看你的接口写的是否正确，或者哪里有问题了