2023年7月14日发(作者：)

e3.0WebApi中使⽤Swagger⽣成API⽂档简介为什么使⽤Swagger作为REST APIs⽂档成功⼯具呢？　　1、Swagger可以⽣产⼀个具有互动性的API控制台，开发者可以⽤来学习和尝试API。　　2、Swagger可以⽣产客户端SDK代码⽤于各种不同的平台上的实现。　　3、Swagger⽂件可以在许多不同的平台上从代码注释中⾃动⽣成。　　4、Swagger有⼀个强⼤的社区，⾥⾯有许多强悍的贡献者。Swagger简单介绍

Swagger Codegen：通过Codegen可将描述⽂件⽣成html和cwiki形式的接⼝⽂档，同时也能⽣成多种语⾔的服务端和客户端的代码。可以在后⾯的Swagger Editor中在线⽣成。Swagger UI：提供了⼀个可视化的UI页⾯ 展⽰描述⽂件。接⼝的调⽤⽅、测试、项⽬经理等都可以在该页⾯中对相关接⼝进⾏查阅和做⼀些简单的接⼝请求。该项⽬⽀持在线导⼊⽂件和本地部署UI项⽬。Swagger Editor：类似于markendown编辑器的编辑Swagger描述⽂件的编辑器，改编辑器⽀持实时预览描述⽂件的更新效果。也提供了在线编辑器和本地部署编辑器两种⽅式。Swagger Inspector：感觉和postman差不多，是⼀个可以对接⼝进⾏测试的在线版的postman。⽐在Swagger UI⾥⾯做接⼝请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。Swagger Hub：继承了上⾯所有项⽬的各个功能，你可以以项⽬和版本为单位，将你的描述⽂件上传到Swagger Hub中。在SwaggerHub中跨域完成上⾯项⽬的所有⼯作，需要注册账号，分免费版和收费版。下⾯介绍如何在 Core中使⽤Swagger⽣成API说明⽂档.NET Core3.0已经出来了，那我们就基于.NET Core3.0新建⼀个WebApi项⽬吧。这⾥为了掩饰Swagger的使⽤，就不创建空项⽬了，选择 Core 3.0 创建完成会显⽰这个样⼦，会给我们默认增加⼀个WeatherForecastController

[ApiController] [Route("[controller]")] public class WeatherForecastController : ControllerBase { private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; private readonly ILogger _logger; public WeatherForecastController(ILogger logger) { _logger = logger; } [HttpGet] public IEnumerable Get() { var rng = new Random(); return (1, 5).Select(index => new WeatherForecast { Date = s(index), TemperatureC = (-20, 55), Summary = Summaries[()] }) .ToArray(); } }View Code当我们这个时候运⾏的时候，会出现404的错误（不知道你们有没有遇到，反正我是遇到了），不要着急，我们做以下修改就⾏。⾸先在Controller中将[Route("[controller]")]====》[Route("api/WeatherForecast")]再在中做修改。 这样，我们再访问⼀下，就成功了。

回归今天的主题。如何使⽤Swagger。⾸先，安装依赖包 Core，选择最新版本的。使⽤Nuget或者控制台都可以。.Net Core2.0下，这样是没问题的。但是在.Net Core3.0下，最好使⽤PowerShell进⾏安装。Install-Package Core -Version 5.0.0-rc2

添加并配置Swagger中间件引⼊命名空间using r;在 Startup 类中，导⼊以下命名空间来使⽤ OpenApiInfo 类：using ;将 Swagger ⽣成器添加到 ureServices ⽅法中的服务集合中：在.Net Core3.0之前：//注册Swagger⽣成器，定义⼀个和多个Swagger ⽂档ggerGen(c =>{ rDoc("v1", new Info { Title = "My API", Version = "v1" });});但是在.Net Core 3.0中，要这样写 ggerGen(c => { rDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); });⼀个是new Info(),⼀个是new OpenApiInfo()。这也是为什么最好使⽤Powershell去安装引⽤。否则会报错：TypeLoadException: Could not load type 'nOptions' from assembly ',

Version=3.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'.在Configure⽅法中，启动中间件为⽣成的JSON⽂档和Swagger UI提供服务：//启⽤中间件服务⽣成Swagger作为JSON终结点gger();//启⽤中间件服务对swagger-ui，指定Swagger JSON终结点ggerUI(c =>{ rEndpoint("/swagger/v1/", "My API V1");});

ggerUI(c =>{ rEndpoint("/swagger/v1/", "My API V1"); refix = ;});⾃定义和扩展：Swagger提供了为对象模型进⾏归档和⾃定义UI以匹配你的主题的选项。API信息说明传递给AddSwagger⽅法的配置操作会添加注⼊作者、许可证和说明信息：在.Net Core3.0是这样写的，与之前写法稍微有点区别。请注意下。 ggerGen(c => { rDoc("v1", new OpenApiInfo { Version = "v1", Title = "Bingle API", Description = "⼀个简单的 Core Web API", TermsOfService = new Uri("/taotaozhuanyong"), Contact = new OpenApiContact { Name = "bingle", Email = , Url = new Uri("/taotaozhuanyong"), }, License = new OpenApiLicense { Name = "许可证", Url = new Uri("/taotaozhuanyong"), } }); });

上述完成之后，我们发现，接⼝并没有注释，那么我们怎么来添加注释呢？XML注释在Visual Studio中，在“解决⽅案资源管理器”中右键单击该项⽬，然后选择“编辑 .csproj” 。⼿动将突出显⽰的⾏添加到 .csproj ⽂件 ： true $(NoWarn);1591启⽤ XML 注释，为未记录的公共类型和成员提供调试信息。 警告消息指⽰未记录的类型和成员。 例如，以下消息指⽰违反警告代码1591：warning CS1591: Missing XML comment for publicly visible type or member '()'要在项⽬范围内取消警告，请定义要在项⽬⽂件中忽略的以分号分隔的警告代码列表。 将警告代码追加到 $(NoWarn);

true $(NoWarn);1591ggerGen修改为如下：注意：　　1、对于Linux或者⾮Windows操作系统，⽂件名和路径区分⼤⼩写。例如“”⽂件在Windows上有效，但在CentOS上⽆效　　2、获取应⽤程序路径，建议采⽤ectoryName(typeof(Program).on)这种⽅式或者·rectory这样来获取 ggerGen(c => { rDoc("v1", new OpenApiInfo { Version = "v1", Title = "Bingle API", Description = "⼀个简单的 Core Web API", TermsOfService = new Uri("/taotaozhuanyong"), Contact = new OpenApiContact { Name = "bingle", Email = , Url = new Uri("/taotaozhuanyong"), }, License = new OpenApiLicense { Name = "许可证", Url = new Uri("/taotaozhuanyong"), } }); //为 Swagger JSON and UI设置xml⽂档注释路径 var xmlFile = $"{cutingAssembly().GetName().Name}.xml"; var xmlPath = e(rectory, xmlFile); eXmlComments(xmlPath); });

经过上⾯的配置，接⼝中的⽅法就有注释了： 通过上⾯的操作就可以总结出来，Swagger UI显⽰上述注释代码