vs 生成get set_NET Core 3.x使用Swagger生成在线接口文档

在换了新工作后，我几乎没有接触到.NET Core了，但是，它是我程序语言中的母语，我怎么能忘了它呢？其实我是想等.NET 5 出来的时候再来学习。在.NET 5正式发布之前还是先对之前的东西复习一下，那么就先从.NET Core 使用swagger生成接口文档开始吧。

这里先配一张图吧

我非常期待.NET 5 的到来，到正式发布的时候，一定要去尝尝鲜。好了，继续我们的 .NET Core吧，我这里的环境是

• .NET Core 3.1.401
• Microsoft Visual Studio 16.7.2
• Swashbuckle.AspNetCore 5.5.1

好了，我们来用号称宇宙第一IDE的VS创建一个简单的WebAPI项目

这里我没有采用IIS Express方式运行，而我采用的它自宿主的方式

默认情况下，在调试模式运行的时候，会自动打开默认浏览器，因为在项目有做了设置

我也可以设置我们默认打开的浏览器

在开发WebAPI的时候，没有接口文档是非常难受的，离线文档固然好，但是更新不及时，所以我们需要一个能在线实时更新的的接口文档，那么Swagger备受众多开发者的青睐，所以它成了我们的不二之选。

现在，去引入Swashbuckle.AspNetCore组件，这里有三种方式

• NuGet图形化
• Package Manager命令行 Install-Package Swashbuckle.AspNetCore -Version 5.5.1
• .NET Core CLI 命令 dotnet add CoreDemo.csproj package --version 5.5.1 Swashbuckle.AspNetCore

NeGet方式安装

Package Manager命令行

.NET Core CLI

然后，我们创建一个Controller类

按照向导创建完成后，会基于API模版生成一些基础代码

using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;using Microsoft.AspNetCore.Http;using Microsoft.AspNetCore.Mvc;namespace CoreDemo.Controllers{    [Route("api/[controller]")]    [ApiController]    public class DemoController : ControllerBase    {    }}

为了演示，先写个简单的GET请求接口

using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;using Microsoft.AspNetCore.Http;using Microsoft.AspNetCore.Mvc;namespace CoreDemo.Controllers{    [Route("api/[controller]")]    [ApiController]    public class DemoController : ControllerBase    {        [HttpGet]        public string GetVersion()        {            return "V1.0.0.0";        }    }}

现在就开始配置Swagger，我们需要分别在ConfigureServices和Configure两个方法中添加引用方法

 public void ConfigureServices(IServiceCollection services)        {            services.AddControllers();            services.AddSwaggerGen(c =>            {                c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebAPI接口文档", Version = "v1" });            });        }        // 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.UseSwagger();                app.UseSwaggerUI(c =>                {                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebAPI V1");                });                app.UseDeveloperExceptionPage();            }            app.UseHttpsRedirection();            app.UseRouting();            app.UseAuthorization();            app.UseEndpoints(endpoints =>            {                endpoints.MapControllers();            });        }

现在我们再次运行起来,在浏览器输入https://localhost:5001/swagger来看看效果

初版中的方法上没有注解，现在我们就需要去每个方法上加上注解，这才是接口文档该有的样子

using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;using Microsoft.AspNetCore.Http;using Microsoft.AspNetCore.Mvc;namespace CoreDemo.Controllers{    [Route("api/[controller]")]    [ApiController]    public class DemoController : ControllerBase    {        ///         /// 查看当前版本号        ///         ///         [HttpGet]        public string GetVersion()        {            return "V1.0.0.0";        }    }}

然后去属性->生成->输出中，把XML文档文件这个选项勾

然后再去ConfigureServices中加载我们输出的XML文档

 services.AddSwaggerGen(c =>            {                c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebAPI接口文档", Version = "v1" });                var xmlFilePath = $"{AppContext.BaseDirectory}/{Assembly.GetExecutingAssembly().GetName().Name}.xml";                c.IncludeXmlComments(xmlFilePath, true);            });

另外，我们再把启动路径改成我们的Swagger，这个每次运行就可以直接打开页面进行测试，而不需要手动去输一次

现在运行起来就可以看到接口的说明了

我们还可以给方法中的参数注解，这里有多种，一种就是直接是多个参数，一种是实体，如果是多个简单的参数，我们依然是直接注解的方式即可

 ///         /// 打个招呼吧        ///         /// 名字        ///         [HttpGet("GetName/{name}")]        public string GetName(string name)        {            return $"hello,{name}";        }

如果是以类为参数，就需要在每个属性上加注解

 ///     /// 用户信息    ///     public class UserDto    {        ///         /// 名字        ///         public string Name { get; set; }        ///         /// 年龄        ///         public int Age { get; set; }    }

在我们勾选了XML文档文件之后，如果不加注释的话，就会有警告，极为不友善，像这种警告我们是可以忽略的

在上图中，我们可以看到错误代码，我们把代码添加到属性->生成->错误和警告->取消显示警告这一行中，然后重新生成一次，警告就会消失

好了，今天就先到这里，我们下回再来尝试下多版本API的Swagger文档以及添加请求头。

本文由中年大叔学编程原创，欢迎关注，带你一起长知识！