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()

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

public void ConfigureServices(IServiceCollection services)

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

if (env.IsDevelopment())

app.UseSwagger();

app.UseSwaggerUI(c =>

app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>

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

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

using System;

using System.Collections.Generic;

using System.Linq;

using Microsoft.AspNetCore.Http;

using Microsoft.AspNetCore.Mvc;

namespace CoreDemo.Controllers

[Route("api/[controller]")]

[ApiController]

public class DemoController : ControllerBase

///

///

[HttpGet]

然后去属性->生成->输出中，把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)

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

///

public class UserDto

///

public string Name { get; set; }

///

public int Age { get; set; }

///

/// 用户信息

///

[HttpPost("UserInfo")]

public string UserInfo([FromBody] UserDto user)

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

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

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