.NET core 使用Swagger

时间 2020-07-21 标签 core 使用 swagger

一为何使用swagger

swagger是一种API文档管理的框架web

1.能够在代码中添加注释，且自动生成API文档，无需再次编写，友好的界面让API文档更易懂。json

2.一站式服务，只须要访问swagger的地址，就能够看到全部的后台接口和功能，而且能测试接口状态，真正是完全的先后端分离了。后端

3.内嵌调试，能够查看接口状态和返回值结果很方便。api

思考：若是能在把请求日志也集成进去就更好了。框架

二开始一步一步搭建swagger

第一步：建立一个.NET CORE的web项目（vs2019）前后端分离

到这儿一个.NET core webapi就建立完成了，下面咱们进行swagger的引用和使用。函数

第二步：使用Swagger 工具

选择项目右键单击管理nuget包测试

打开以后，选择浏览输入 Swashbuckle.AspNetCore ，选择后安装this

而后依次点击肯定和接受，就算安装完成了。安装完成后，依赖项里面就会多出来一个包的引用。

包引入完成后，下一步就是须要注册Swagger了，这里咱们能够建立一个类来存放注册的信息（代码会整洁，逻辑也会清晰一点），首先新建一个文件夹名字随便取，在新建一个Swagger类。

须要引用

using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

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

namespace WebApi.Core.Api.SetUpService
{
    public static class SwaggerSetUp
    {
        public static void AddSwaggerSetup(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定义成全局变量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文档——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);
            });

        }
    }
}

接下来就是须要到 Startup 类，找到ConfigureServices 注册咱们写好的服务，能够把光标放在AddSwaggerSetup按12，就会跳转到咱们写的SwaggerSetUp方法中。

接着在StartUp类中找到Configure方法编辑，这里面RoutePrefix 就是你须要访问的url路径后面的路由好比咱们访问 localhost:8080/ApiDoc就能够跳转到Swagger的页面

咱们把IIS 启动的注释，项目启动的Url改为根目录

修改后按F5启动项目，没有找到

接下来咱们输入/ApiDoc敲回车，就能够了，这就是配置 RoutePrefix 属性的做用。

咱们找到Startup中的Configure把RoutePrefix 设置为空再按F5启动，直接根目录打开就进入了Swagger页面中。

接下来咱们实际使用一下，先把自带的Controller删除，而后建立一个BaseController继承ControllerBase ，右键Controllers选择添加-控制器，选一个空的控制器，取名字

BaseController是一个基类，目的是为了自定义路由，而后放一些公共的方法，这样你每次新建一个类就只须要继承BaseController类无需作太多重复工做了

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

添加代码

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

namespace WebApi.Core.Api.Controllers
{
    public class UsersController : BaseController
    {
        [HttpGet]
        public IActionResult Hello()
        {
            return Ok("Hello World");
        }
    }
}

F5启动，这样一个简单的Swagger就已经搭建完成。可是比较简单，功能也不是不少

下面继续在Swagger下面添加一些东西。文档注释，咱们新建一个Model类库，由于Swagger不只能够把接口注释显示，也能够对实体进行注释的显示。

右键解决方案->添加->新建项目->选择类库->建立类库

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

XML文件放在同一个位置方便管理

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

 public static void AddSwaggerSetup(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定义成全局变量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文档——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);

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

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

            });

        }

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

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

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

咱们在UsersController 添加以下函数

/// <summary>
        /// 用户实体类测试
        /// </summary>
        /// <param name="usersModel"></param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult UsersTestSwagger(UsersModel usersModel)
        {
            return Ok(usersModel);
        }

而后F5启动，这里咱们看到 model类显示出来了，可是没有注释为何呢

通过排查发现SwaggerSetUp类中的AddSwaggerSetup 函数里面有一段代码写错了，由于复制粘贴的问题，这种问题咱们常常会犯，因此若是能够，之后尽可能不要复制粘贴，还能加深你敲代码的能力。

改好以后从新F5 ，已经把model类里面的注释也显示出来了，

若是咱们不想在Swagger 里面显示出来那就能够在函数上面加一个特性 [ApiExplorerSettings(IgnoreApi = true)]

能够看到 Hello 这个函数就被隐藏了

到此，.net core 搭建和使用Swagger就算完成了，是否是很简单。

下面在简单介绍一下，请求和响应应该怎么去看

咱们单击try it out

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

.NET core 使用Swagger

一 为何使用swagger

二 开始一步一步搭建swagger

一为何使用swagger

二开始一步一步搭建swagger