在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 }
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· DeepSeek “源神”启动!「GitHub 热点速览」
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器