在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)

posted @   平元兄  阅读(385)  评论(1编辑  收藏  举报
编辑推荐:
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
阅读排行:
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· DeepSeek “源神”启动!「GitHub 热点速览」
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器
点击右上角即可分享
微信分享提示