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

程序员文章站 2022-06-29 21:22:26

参考地址，官网：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=visual-studio 与https://www.ji ......

参考地址，官网：

与

当一个webapi完成之后，书写api文档是一件非常头疼的事，因为不仅要写得清楚，能让调用接口的人看懂，又是非常耗时耗力的一件事。在之前的一篇随笔中（），记载.net framework中webapi生成文档的时候，通过访问指定的路径，就可以获取到api文档。在.net core中又怎么生成api文档呢？使用swagger。

为什么使用swagger作为rest apis文档成功工具呢？

　　1、swagger可以生产一个具有互动性的api控制台，开发者可以用来学习和尝试api。

　　2、swagger可以生产客户端sdk代码用于各种不同的平台上的实现。

　　3、swagger文件可以在许多不同的平台上从代码注释中自动生成。

　　4、swagger有一个强大的社区，里面有许多强悍的贡献者。

swagger简单介绍

swagger官网：

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

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中。在swagger hub中跨域完成上面项目的所有工作，需要注册账号，分免费版和收费版。

下面介绍如何在asp.net core中使用swagger生成api说明文档

.net core3.0已经出来了，那我们就基于.net core3.0新建一个webapi项目吧。

这里为了掩饰swagger的使用，就不创建空项目了，选择asp.net core 3.0

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

创建完成会显示这个样子，会给我们默认增加一个weatherforecastcontroller

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

 [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();
     }
 }

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

首先在controller中将[route("[controller]")]====》[route("api/weatherforecast")]

再在launchsettings.json中做修改。

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

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

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

回归今天的主题。如何使用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。生成的描述终结点的文档显示如下：

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

可在 http://localhost:<port>/swagger 找到 swagger ui。通过 swagger ui 浏览 api文档，如下所示。

ASP.NET Core 3.0 WebApi中使用Swagger生成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，就看到上述添加的信息

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

上述完成之后，我们发现，接口并没有注释，那么我们怎么来添加注释呢？

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修改为如下：

注意：

　　1、对于linux或者非windows操作系统，文件名和路径区分大小写。例如“mywebapiuseswagger.xml”文件在windows上有效，但在centos上无效

　　2、获取应用程序路径，建议采用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);
 });

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

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

通过上面的操作就可以总结出来，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}";
 }

可以看到如下效果：

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

描述响应类型

使用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}";
 }

以下是看到的效果

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