ASP.NET Core WebApi使用Swagger生成API说明文档

首先微软官方给了简单的例子，参考这个例子就可以生成简单的可视化文档。

微软官网文档地址:点击打开链接

首先新建一个WebAPI项目，Edu.Swagger

然后打开“程序包管理控制台”使用NuGet安装  Swashbuckle.AspNetCore

Install-Package Swashbuckle.AspNetCore

配置Startup.cs文件

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

下面我用v1,v2分别表示两个版本的接口

services.AddSwaggerGen(option =>
            {
                option.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "第一版 API",
                    Description = "第一版 ASP.NET Core Web API",
                    TermsOfService = "None",
                    Contact = new Contact
                    {
                        Name = "张海涛",
                        Email = "993887459@qq.com",
                        Url = "https://blog.csdn.net/haitaoDoit"
                    },
                    License = new License
                    {
                        Name = "Use under LICX",
                        Url = "https://example.com/license"
                    }
                });

                option.SwaggerDoc("v2", new Info
                {
                    Version = "v2",
                    Title = "第二版 API",
                    Description = "第二版 ASP.NET Core Web API",
                    TermsOfService = "None",
                    Contact = new Contact
                    {
                        Name = "张海涛",
                        Email = "993887459@qq.com",
                        Url = "https://blog.csdn.net/haitaoDoit"
                    },
                    License = new License
                    {
                        Name = "Use under LICX",
                        Url = "https://example.com/license"
                    }
                });

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

app.UseSwagger();
app.UseSwaggerUI(c =>
{
     c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
     c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
});

现在启动浏览器

最基本的UI界面已经出来了，但是现在是没有获取到方法描述的。

右键项目属性，启用XML文档文件，并且添加1591禁止显示警告

在Startup.ConfigureServices 中services.AddSwaggerGen(option =>添加

 为 Swagger JSON and UI设置xml文档注释路径

option.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Edu.Model.xml"));//这里增加model注释，返回值会增加注释：需要Edu.Model项目属性，生成中输出xml文件
option.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Edu.Swagger.xml"));

再次运行项目,就可以看到代码中的说明了

前面我们提到我们设计了两个版本，v1,v2，那么怎么实现呢，下面在代码中添加

[ApiExplorerSettings(GroupName = "v1")]
[ApiExplorerSettings(GroupName = "v2")]

 

 

再次运行项目，默认打开V1版本

点击右上角下拉框选择V2那么就会显示V2的接口

本文Demo下载地址：点击打开链接

GitHub地址：https://github.com/zhanght919/Edu.Swagger

总结

本文从手工书写api文档的痛处说起，进而引出Swagger这款自动生成api说明文档的工具！然后通过通俗易懂的文字结合图片为大家演示了如何在一个ASP.NET Core WebApi中使用SwaggerUI生成api说明文档。最后又为大家介绍了一些ASP.NET Core 中Swagger的一些高级用法！希望对大家在ASP.NET Core中使用Swagger有所帮助！