Asp.Net Core使用swagger生成api文档的完整步骤

 更新时间:2019年12月01日 09:52:05   作者:willingtolove  
这篇文章主要给大家介绍了关于Asp.Net Core使用swagger生成api文档的完整步骤,文中通过示例代码介绍的非常详细,对大家学习或者使用Asp.Net Core具有一定的参考学习价值,需要的朋友们下面来一起学习学习吧

脚本之家 / 编程助手:解决程序员“几乎”所有问题!
脚本之家官方知识库 → 点击立即使用

前言

.Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag。两者的配置大同小异。这里以NSwag为例。

一、前期准备

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

新建asp.net core项目,此处略过;

新建apicontroller,并编写测试代码;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
[Route("api/[controller]")]
[ApiController]
public class UserApiController : ControllerBase
{
/// <summary>
/// 获取用户信息,根据用户id
/// </summary>
/// <param name="id">用户id</param>
/// <returns></returns>
[HttpGet("getuser/{id}")]
public ActionResult GetUser(int id)
{
 User u = new User { Id=1,Name="Jack"};
 return Ok(new { ok = true, data = u });
}
/// <summary>
/// 添加用户
/// </summary>
/// <param name="user">用户信息</param>
/// <returns></returns>
[HttpPost("postuser")]
public ActionResult AddUser([FromBody]User user)
{
 return Ok(new { ok = true, data = user });
}
}
1
2
3
4
5
6
7
8
9
10
11
public class User
{
/// <summary>
/// 用户id
/// </summary>
public int Id { get; set; }
/// <summary>
/// 用户姓名
/// </summary>
public string Name { get; set; }
}

2、使用nuget安装 NSwag.AspNetCore

方式一:通过vs图形界面安装;


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

1
Install-Package NSwag.AspNetCore

二、配置Swagger

1、添加并配置 Swagger 中间件

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

1
2
3
4
5
6
7
public void ConfigureServices(IServiceCollection services)
{
 services.AddControllersWithViews();
  
 // Register the Swagger services
 services.AddSwaggerDocument()
}

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

1
2
3
4
5
6
7
8
9
10
public void Configure(IApplicationBuilder app)
{
 app.UseStaticFiles();
 
 // Register the Swagger generator and the Swagger UI middlewares
 app.UseOpenApi();
 app.UseSwaggerUi3();
 
 app.UseMvc();
}

启动应用。 转到:

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

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

2、自定义 API 文档

API 信息和说明

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
public void ConfigureServices(IServiceCollection services)
{
 //services.AddControllers();
 services.AddControllersWithViews();
 
 services.AddSwaggerDocument(config =>
 {
  config.PostProcess = document =>
  {
   document.Info.Version = "v1";
   document.Info.Title = "UserManageApp API";
   document.Info.Description = "A simple ASP.NET Core web API";
   document.Info.TermsOfService = "None";
   document.Info.Contact = new NSwag.OpenApiContact
   {
    Name = "张三",
    Email = string.Empty,
    Url = "https://example.com"
   };
   document.Info.License = new NSwag.OpenApiLicense
   {
    Name = "Use under LICX",
    Url = "https://example.com/license"
   };
  };
 });
}

Swagger UI 显示版本的信息:

XML 注释

若要启用 XML 注释,请执行以下步骤:

以windows先使用vs为例:

  • 在“解决方案资源管理器”中右键单击该项目,然后选择“编辑 .csproj” 。
  • 手动将突出显示的行添加到 .csproj 文件 :

三、参考

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-3.0&tabs=visual-studio

*以上讲解知识入门级的,能大体使用起来,能满足一般性需求;

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对脚本之家的支持。

蓄力AI

微信公众号搜索 “ 脚本之家 ” ,选择关注

程序猿的那些事、送书等活动等着你

原文链接:https://www.cnblogs.com/willingtolove/p/11963794.html

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。
如若内容造成侵权/违法违规/事实不符,请将相关资料发送至 reterry123@163.com 进行投诉反馈,一经查实,立即处理!

相关文章

最新评论