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

前言

.net core中有两个集成nswag的包，分别为swashbuckle和nswag。两者的配置大同小异。这里以nswag为例。

一、前期准备

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

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

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

 [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 });
 }
 }

 public class user
 { 
 /// <summary>
 /// 用户id
 /// </summary>
 public int id { get; set; }
 /// <summary>
 /// 用户姓名
 /// </summary>
 public string name { get; set; }
 }

2、使用nuget安装 nswag.aspnetcore

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

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

install-package nswag.aspnetcore

二、配置swagger

1、添加并配置 swagger 中间件

在应用的startup类中的configureservices 方法中，注册所需的 swagger 服务：

  public void configureservices(iservicecollection services)
  {
   services.addcontrollerswithviews();
   
   // register the swagger services
   services.addswaggerdocument()
  }

在 startup类中的configure 方法中，启用中间件为生成的 swagger 规范和 swagger ui 提供服务：

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 方法的配置操作会添加诸如作者、许可证和说明的信息：

  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

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

总结

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