vs2019 .net core3.0 Swagger

Liu_某

已于 2024-03-02 15:31:36 修改

阅读量1.1k

点赞数 26

分类专栏： swagger .net core 文章标签： .netcore

于 2024-03-02 15:18:20 首次发布

本文链接：https://blog.csdn.net/qq_61596453/article/details/136416028

版权

swagger 同时被 2 个专栏收录

2 篇文章 0 订阅

订阅专栏

.net core

2 篇文章 0 订阅

订阅专栏

一为什么使用swagger

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

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

2.一站式服务，只需要访问swagger的地址，就可以看到所有的后台接口和功能，并且能测试接口状态，真正是彻底的前后端分离了。

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

思考：如果能在把请求日志也集成进去就更好了。

二开始一步一步搭建swagger

第一步：创建一个.NET Core Web Api项目（vs2019）

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

第二步：使用Swagger

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

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

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

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

SwaggerSetup代码

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

namespace test.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方法中。

//注册Swagger服务
services.AddSwaggerSetup();

//可能会报错，添加一下引用即可。（Alt+Shit+F10）

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

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerSetup();

            services.AddControllers();
        }

 // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseSwagger();
            app.UseSwaggerUI(u =>
            {
                u.SwaggerEndpoint($"/swagger/V1/swagger.json","WebApi.Core V1");
                //路径配置 配置为空表示在根域名（localhost:8001）访问该文件
                //注意 localhost:8001/swagger是访问不到的 去launchSettings.json把launchUrl去掉
                //如果想换一个路径 直接写 u.RoutePrefix = "Apidoc";
                u.RoutePrefix = "Apidoc";
            });

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

我们把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
{
    [Route("api/[controller]")]
    [ApiController]
    public class UsersController : BaseController
    {
        [HttpGet]
        public IActionResult Hello()
        {
            return Ok("Hello World");
        }
    }
}

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

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

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

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

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

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

namespace test.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);

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

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

            });

        }
    }
}

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

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

这里我们加了注释，启动F5(如果部署到某个服务器上注释没显式说明没有生成xml，重新生成一下解决方案即可) 看看效果，从下面的图片看，是没问题的注释已经显示出来了，但是model在哪里，为什么没有显示出来

我们在UsersController 添加如下函数

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

然后F5启动，这里我们看到 model类显示出来了，但是没有注释为什么呢