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

 更新时间:2019-12-02 07:03:43   作者:佚名   我要评论(0)

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


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


前言

.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

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

总结

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

您可能感兴趣的文章:

  • Asp.net core WebApi 使用Swagger生成帮助页实例
  • .Net Core2.1 WebAPI新增Swagger插件详解
  • .NET Core利用swagger进行API接口文档管理的方法详解
  • Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解

相关文章

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

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

    前言 .Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag。两者的配置大同小异。这里以NSwag为例。 一、前期准备 1、初始化asp.net core 测试项目 新
    2019-12-02
  • Spring Cloud Ubuntu环境部署的步骤与注意事项

    Spring Cloud Ubuntu环境部署的步骤与注意事项

    SpringCloud相关环境部署 RabbitMQ部署 Redis部署 Nacos部署 RabbitMQ 不采用更新安装包方式安装 apt-get install 。采用从官网下载对应版本安装包,采
    2019-12-02
  • Springboot整合thymleaf模板引擎过程解析

    Springboot整合thymleaf模板引擎过程解析

    这篇文章主要介绍了Springboot整合thymleaf模板引擎过程解析,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2019-11-29
  • Java实现TCP/IP协议的收发数据(服务端)代码实例

    Java实现TCP/IP协议的收发数据(服务端)代码实例

    这篇文章主要介绍了Java实现TCP/IP协议的收发数据(服务端)代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以
    2019-11-29
  • python 监测内存和cpu的使用率实例

    python 监测内存和cpu的使用率实例

    我就废话不多说了,直接上代码吧! import paramiko import pymysql import time linux = ['192.168.0.179'] def connectHost(ip, uname='shenyuming', passwd='
    2019-11-29
  • javascript实现切割轮播效果

    javascript实现切割轮播效果

    本文实例为大家分享了javascript实现切割轮播的具体代码,供大家参考,具体内容如下 效果 代码 <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8
    2019-11-29
  • 关于Python-faker的函数效果一览

    关于Python-faker的函数效果一览

    tags faker 随机 虚拟 faker文档链接 代码程序: # -*- coding=utf-8 -*- import sys from faker import Factory reload(sys) sys.setdefaultencoding('utf8') f
    2019-11-29
  • javascript实现商品图片放大镜

    javascript实现商品图片放大镜

    优化原因 现在的电商商城项目解决的主要是购买商品的问题,那么购买商品主要要看清楚商品表面外形的主要特征和细节,如果图片处理过小,或者细节过于模糊,就需要做
    2019-11-29
  • javascript实现异形滚动轮播

    javascript实现异形滚动轮播

    本文实例为大家分享了js异形滚动轮播的具体代码,供大家参考,具体内容如下 运动过程研究 让每个元素走到前一个标签的位置。 3走到2 2走到1 1走到0 0走到6
    2019-11-29
  • Vue请求java服务端并返回数据代码实例

    Vue请求java服务端并返回数据代码实例

    这篇文章主要介绍了Vue请求java服务端并返回数据代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 最近
    2019-11-29

最新评论