ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介

时间  2019-12-01 标签 asp.net asp core 3.0 webapi 使用 swagger 生成 api 文档 简介

ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介

当一个WebApi完成以后，书写API文档是一件很是头疼的事，由于不只要写得清楚，能让调用接口的人看懂，又是很是耗时耗力的一件事。在以前的一篇随笔中（https://www.cnblogs.com/taotaozhuanyong/p/11567017.html），记载.Net Framework中WebApi生成文档的时候，经过访问指定的路径，就能够获取到Api文档。在.NET Core中又怎么生成API文档呢？使用Swagger。html

为何使用Swagger做为REST APIs文档成功工具呢？shell

　　一、Swagger能够生产一个具备互动性的API控制台，开发者能够用来学习和尝试API。json

　　二、Swagger能够生产客户端SDK代码用于各类不一样的平台上的实现。api

　　三、Swagger文件能够在许多不一样的平台上从代码注释中自动生成。app

　　四、Swagger有一个强大的社区，里面有许多强悍的贡献者。dom

下面介绍如何在ASP.NET Core中使用Swagger生成API说明文档工具

.NET Core3.0已经出来了，那咱们就基于.NET Core3.0新建一个WebApi项目吧。post

这里为了掩饰Swagger的使用，就不建立空项目了，选择ASP.NET 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<WeatherForecastController> _logger; public WeatherForecastController(ILogger<WeatherForecastController> logger) { _logger = logger; } [HttpGet] public IEnumerable<WeatherForecast> Get() { var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } } View Code

当咱们这个时候运行的时候，会出现404的错误（不知道大家有没有遇到，反正我是遇到了），不要着急，咱们作如下修改就行。

首先在Controller中将[Route("[controller]")]====》[Route("api/WeatherForecast")]

再在launchSettings.json中作修改。

 

 这样，咱们再访问一下，就成功了。

 

 回归今天的主题。如何使用Swagger。

首先，安装依赖包 Swashbuckle.AspNetCore，选择最新版本的。使用Nuget或者控制台均可以。.Net Core2.0下，这样是没问题的。可是在.Net Core3.0下，最好使用PowerShell进行安装。

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc2

 

 添加并配置Swagger中间件

引入命名空间

using Swashbuckle.AspNetCore.Swagger;

在 Startup 类中，导入如下命名空间来使用 OpenApiInfo 类：

using Microsoft.OpenApi.Models;

将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：

在.Net  Core3.0以前：

//注册Swagger生成器，定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
     c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

可是在.Net Core 3.0中，要这样写

 services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
 });

一个是new Info(),一个是new OpenApiInfo()。这也是为何最好使用Powershell去安装引用。不然会报错：

TypeLoadException: Could not load type 'Microsoft.AspNetCore.Mvc.MvcJsonOptions' from assembly 'Microsoft.AspNetCore.Mvc.Formatters.Json, Version=3.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'.

在Configure方法中，启动中间件为生成的JSON文档和Swagger UI提供服务：

//启用中间件服务生成Swagger做为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui，指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

启动应用，并导航到http://localhost:<post>/swagger/v1/swagger.sjon。生成的描述终结点的文档显示以下：

 

 

 可在 http://localhost:<port>/swagger 找到 Swagger UI。 经过 Swagger UI 浏览 API文档，以下所示。

 

 

 要在应用的根 (http://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

自定义和扩展：

Swagger提供了为对象模型进行归档和自定义UI以匹配你的主题的选项。

API信息说明

传递给AddSwagger方法的配置操做会添加注入做者、许可证和说明信息：在.Net Core3.0是这样写的，与以前写法稍微有点区别。请注意下。

 services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new OpenApiInfo
     {
         Version = "v1",
         Title = "Bingle API",
         Description = "一个简单的ASP.NET Core Web API",
         TermsOfService = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         Contact = new OpenApiContact
         {
             Name = "bingle",
             Email = string.Empty,
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         },
         License = new OpenApiLicense
         {
             Name = "许可证",
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         }
     });
 });

访问地址http://localhost:<port>/swagger，就看到上述添加的信息

 

 

上述完成以后，咱们发现，接口并无注释，那么咱们怎么来添加注释呢？

XML注释

在Visual Studio中，在“解决方案资源管理器”中右键单击该项目，而后选择“编辑 <project_name>.csproj” 。手动将突出显示的行添加到 .csproj 文件 ：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

启用 XML 注释，为未记录的公共类型和成员提供调试信息。 警告消息指示未记录的类型和成员。 例如，如下消息指示违反警告代码 1591：

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

要在项目范围内取消警告，请定义要在项目文件中忽略的以分号分隔的警告代码列表。 将警告代码追加到 $(NoWarn); 

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

services.AddSwaggerGen修改成以下：

注意：

　　一、对于Linux或者非Windows操做系统，文件名和路径区分大小写。例如“MyWebApiUseSwagger.xml”文件在Windows上有效，但在CentOS上无效

　　二、获取应用程序路径，建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)这种方式或者·AppContext.BaseDirectory这样来获取

 services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new OpenApiInfo
     {
         Version = "v1",
         Title = "Bingle API",
         Description = "一个简单的ASP.NET Core Web API",
         TermsOfService = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         Contact = new OpenApiContact
         {
             Name = "bingle",
             Email = string.Empty,
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         },
         License = new OpenApiLicense
         {
             Name = "许可证",
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         }
     });
     //为 Swagger JSON and UI设置xml文档注释路径
     var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
     var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
     c.IncludeXmlComments(xmlPath);
 });

 

通过上面的配置，接口中的方法就有注释了：

 

 经过上面的操做就能够总结出来，Swagger UI显示上述注释代码 <summary>元素的内部文本做为api大的注释！固然你还能够将 remarks 元素添加到 Get 操做方法文档。 它能够补充 <summary> 元素中指定的信息，并提供更可靠的 Swagger UI。 <remarks> 元素内容可包含文本、JSON 或 XML。 代码以下：

 /// <summary>
 /// 这是一个带参数的get请求
 /// </summary>
 /// <remarks>
 /// 例子:
 /// Get api/Values/1
 /// </remarks>
 /// <param name="id">主键</param>
 /// <returns>测试字符串</returns>  
 [HttpGet("{id}")]
 public ActionResult<string> Get(int id)
 {
     return $"你请求的id是{id}";
 }

能够看到以下效果：

 

 描述响应类型

使用WebApi的开发人员最关心的问题是返回的内容，特别是响应类型和错误代码。在XML注释和数据中表示相应类型的错误代码。Get 操做成功后返回HTTP 201状态码。发布的请求正文为NULL，将返回HTTP 400状态代码。若是Swagger UI中没有提供合适的文档，那么使用者会缺乏对这些预期的结果的了解。

在如下的实例中，经过突出的行解决此问题：

 /// <summary>
 /// 这是一个带参数的get请求
 /// </summary>
 /// <remarks>
 /// 例子:
 /// Get api/Values/1
 /// </remarks>
 /// <param name="id">主键</param>
 /// <returns>测试字符串</returns> 
 /// <response code="201">返回value字符串</response>
 /// <response code="400">若是id为空</response>  
 // GET api/values/2
 [HttpGet("{id}")]
 [ProducesResponseType(201)]
 [ProducesResponseType(400)]
 public ActionResult<string> Get(int id)
 {
     return $"你请求的id是{id}";
 }

如下是看到的效果

 

如何使用Swagger UI进行测试？

点击Try it out

 

 输入参数，再点击Excute：

 

 获得的响应结果：

 

以上即是在.Net Core 3.0 WebApi中使用Swagger的基本介绍。以及在.Net Core3.0下如何建立WebApi，在使用Swagger在和之前有什么区别的的介绍。

联系我们 沪ICP备13005482号-10