在ASP.NET Core web API中使用Swagger/OpenAPI（NSwag）

 

简介

NSwag有以下能力：

• SwaggerUI界面和Swagger生成器。
• 灵活的代码生成能力

有了NSwag，你可以不需要一个已经出来的API，你可以用第三方的API来与Swagger配合并且生成一个客户端实现。NSwag可以加快你的开发周期，并且轻松适应API的改变，升级，迭代。

一.安装包（NSwag.AspNetCore）

右击项目选择管理Nuget程序包

按名字搜索包，然后选择包，选择对应版本，然后安装

二.注册Swagger服务并启用中间件

在Startup.ConfigureServices方法中注册需要的Swagger服务

	public void ConfigureServices(IServiceCollection services)
	{
	services.AddDbContext<TodoContext>(opt =>
	opt.UseInMemoryDatabase("TodoList"));
	services.AddMvc();
	// Register the Swagger services
	services.AddSwaggerDocument();
	}

在Startup.Configure方法中启用生成Swagger规范文档(openapi.json)和SwaggerUI的中间件

	public void Configure(IApplicationBuilder app)
	{
	app.UseStaticFiles();
	// Register the Swagger generator and the Swagger UI middlewares
	app.UseOpenApi();
	app.UseSwaggerUi3();
	app.UseMvc();
	}

运行程序，通过如下地址导航到对应的

• 通过http://localhost:<port>/swagger查看SwaggerUI界面
• 通过`http://localhost:/swagger/v1/swagger.json查看Swagger规范文档（openapi.json）

使用NSwagStudio生成代码

下载并使用NSwagStudio,由于我没用过这个，不做详解

API信息和描述

如果您想在Swagger UI中添加一些对API的描述信息，比如作者、许可证、服务条款等信息：
在Program.cs类中引入OpenApiInfo类的命名空间

using Microsoft.OpenApi.Models;

然后在Program.cs文件中的ConfigureServices方法中通过services.AddSwaggerGen方法的配置对象进行就改，模板如下：

	services.AddSwaggerDocument(config =>
	{
	config.PostProcess = document =>
	{
	document.Info.Version = "v1";
	document.Info.Title = "ToDo API";
	document.Info.Description = "A simple ASP.NET Core web API";
	document.Info.TermsOfService = "None";
	document.Info.Contact = new NSwag.OpenApiContact
	{
	Name = "Shayne Boyer",
	Email = string.Empty,
	Url = "https://twitter.com/spboyer"
	};
	document.Info.License = new NSwag.OpenApiLicense
	{
	Name = "Use under LICX",
	Url = "https://example.com/license"
	};
	};
	});

对应SwaggerUI中

XML注释

如果您想启用XML注释以及生成对应的XML注释文档，右击的的项目文件，然后点击编辑项目文件

添加<GenerateDocumentationFile>true</GenerateDocumentationFile>即可启用XML注释

	<PropertyGroup>
	<!--生成XML注释文档-->
	<GenerateDocumentationFile>true</GenerateDocumentationFile>
	</PropertyGroup>

开启这个功能后，如果您的程序中有没有经过XML注释的类型或者成员，您将会看到如下警告信息：

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

您觉得烦，可以在编辑项目文件中添加<NoWarn>$(NoWarn);1591</NoWarn>来取消这种警告

	<PropertyGroup>
	<!--取消1591警告信息-->
	<NoWarn>$(NoWarn);1591</NoWarn>
	</PropertyGroup>

您也可以通过如下宏定义的方式对整段代码取消1591警告信息

	namespace SwashbuckleSample.Models
	{
	#pragma warning disable CS1591
	public class TodoContext : DbContext
	{
	public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }
	public DbSet<TodoItem> TodoItems => Set<TodoItem>();
	}
	#pragma warning restore CS1591
	}

更多请参考：在ASP.NET Core web API中使用Swagger/OpenAPI（Swashbuckle）

 

分类: .Net