怎么在Asp.Net Core中使用swagger生成一个api文档

tangjin

作者

本篇文章为大家展示了怎么在Asp.Net Core中使用swagger生成一个api文档，内容简明扼要并且容易理解，绝对能使你眼前一亮，通过这篇文章的详细介绍希望你能有所收获。

一、前期准备

1、初始化asp.net core 测试项目

新建asp.net core项目，此处略过；

新建apicontroller，并编写测试代码；

[Route("api/[controller]")]
[ApiController]
publicclassUserApiController:ControllerBase
{
///<summary>
///获取用户信息，根据用户id
///</summary>
///<paramname="id">用户id</param>
///<returns></returns>
[HttpGet("getuser/{id}")]
publicActionResultGetUser(intid)
{
Useru=newUser{Id=1,Name="Jack"};
returnOk(new{ok=true,data=u});
}
///<summary>
///添加用户
///</summary>
///<paramname="user">用户信息</param>
///<returns></returns>
[HttpPost("postuser")]
publicActionResultAddUser([FromBody]Useruser)
{
returnOk(new{ok=true,data=user});
}
}

publicclassUser
{
///<summary>
///用户id
///</summary>
publicintId{get;set;}
///<summary>
///用户姓名
///</summary>
publicstringName{get;set;}
}

2、使用nuget安装 NSwag.AspNetCore

方式一：通过vs图形界面安装；

方式二：通过nuget 命令安装：

Install-PackageNSwag.AspNetCore

二、配置Swagger

1、添加并配置 Swagger 中间件

在应用的Startup类中的ConfigureServices 方法中，注册所需的 Swagger 服务：

publicvoidConfigureServices(IServiceCollectionservices)
{
services.AddControllersWithViews();

//RegistertheSwaggerservices
services.AddSwaggerDocument()
}

在 Startup类中的Configure 方法中，启用中间件为生成的 Swagger 规范和 Swagger UI 提供服务：

publicvoidConfigure(IApplicationBuilderapp)
{
app.UseStaticFiles();

//RegistertheSwaggergeneratorandtheSwaggerUImiddlewares
app.UseOpenApi();
app.UseSwaggerUi3();

app.UseMvc();
}

启动应用。转到：

http://localhost:/swagger，以查看 Swagger UI。

http://localhost:/swagger/v1/swagger.json，以查看 Swagger 规范。

2、自定义 API 文档

API 信息和说明

在 Startup.ConfigureServices 方法中，传递给 AddSwaggerDocument 方法的配置操作会添加诸如作者、许可证和说明的信息：

publicvoidConfigureServices(IServiceCollectionservices)
{
//services.AddControllers();
services.AddControllersWithViews();

services.AddSwaggerDocument(config=>
{
config.PostProcess=document=>
{
document.Info.Version="v1";
document.Info.Title="UserManageAppAPI";
document.Info.Description="AsimpleASP.NETCorewebAPI";
document.Info.TermsOfService="None";
document.Info.Contact=newNSwag.OpenApiContact
{
Name="张三",
Email=string.Empty,
Url="https://example.com"
};
document.Info.License=newNSwag.OpenApiLicense
{
Name="UseunderLICX",
Url="https://example.com/license"
};
};
});
}

Swagger UI 显示版本的信息：