.NET中的Swagger使用示例详解

2024-03-04 0 625
目录
  • 前言
  • 一、Swagger是什么?
  • 二、如何Swagger文档说明的信息
    • 1.在AddSwaggerGen方法中写入文档信息
    • 2.运行效果
  • 二、文档UI界面标题、路由设置
    • 1.在中间件UseSwaggerUI方法中配置
  • 三、文档UI界面添加接口注释
    • 1.在.csproj中配置
    • 2.在AddSwaggerGen方法中配置IncludeXmlComments
  • 四、对接口进行分组
    • 1.在AddSwaggerGen、UseSwaggerUI分别添加如下信息
    • 2.在controller或者action上打上ApiExplorerSettings特性
  • 总结

    前言

    现在很多项目都是前后端分离的项目,后端写好接口跟前端对接,需要后端提供接口文档、参数等注释,这上面花时间着这些东西,接口修改又要去修改文档,很不方便前后端人员开发

    一、Swagger是什么?

    Swagger (OpenAPI) 是一个与语言无关的规范,用于描述 REST API。

    OpenAPI 与 Swagger关系Swagger 项目已于 2015 年捐赠给 OpenAPI 计划,自此它被称为 OpenAPI,这两个名称可互换使用。 不过,“OpenAPI”指的是规范。简而言之:OpenAPI 是一种规范。Swagger 是一种使用 OpenAPI 规范的工具。 例如,OpenAPIGenerator 和 SwaggerUI。

    目前从NETCore从3.1起已经集成Sawwger,无需再去引用库,创建项目后运行API项目自动Sawwger接口文档的页面

    介绍大家可能会关注的一些点

    二、如何Swagger文档说明的信息

    .NET中的Swagger使用示例详解

    1.在AddSwaggerGen方法中写入文档信息

    代码如下(示例):

    builder.Services.AddSwaggerGen(options =>
    {
    //诸如作者、文档说明的信息
    options.SwaggerDoc(\”v1\”, new OpenApiInfo
    {
    Version = \”v1\”,
    Title = \”我的API\”,
    Description = \”这是我的netcoreAPI项目\”,//描述信息
    Contact = new OpenApiContact
    {
    Name = \”我是小小鱼\”,
    Url = new Uri(\”https://blog.csdn.net/qq_42335551\”)
    }
    });

    2.运行效果

    如图(示例):

    .NET中的Swagger使用示例详解

    二、文档UI界面标题、路由设置

    如何修改标签页的名、和地址要怎么修改呢

    .NET中的Swagger使用示例详解

    1.在中间件UseSwaggerUI方法中配置

    app.UseSwagger();
    app.UseSwaggerUI(c => {
    c.DocumentTitle = \”后台接口列表\”; //标签页标题
    c.SwaggerEndpoint(\”/swagger/v1/swagger.json\”, \”公共模块\”);//接口文档json文件
    c.RoutePrefix =string.Empty;// 注:这里的路由修改后,launchSettings.json中的launchUrl对应需要调整为\”\”
    });

    在次启动项目 已经变成修改后的标签页和地址

    .NET中的Swagger使用示例详解

    三、文档UI界面添加接口注释

    如何添加接口的注释呢

    .NET中的Swagger使用示例详解

    1.在.csproj中配置

    在解决方案资源管理器中右键单击该项目。 将 GenerateDocumentationFile 添加到 .csproj 文件中PropertyGroup节点下

    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    2.在AddSwaggerGen方法中配置IncludeXmlComments

    代码如下(示例):

    builder.Services.AddSwaggerGen(options =>
    {
    //诸如作者、文档说明的信息
    options.SwaggerDoc(\”v1\”, new OpenApiInfo
    {
    Version = \”v1\”,
    Title = \”我的API\”,
    Description = \”这是我的netcoreAPI项目\”,//描述信息
    Contact = new OpenApiContact
    {
    Name = \”我是小小鱼\”,
    Url = new Uri(\”https://blog.csdn.net/qq_42335551\”)
    }
    });
    var xmlFilename = $\”{Assembly.GetExecutingAssembly().GetName().Name}.xml\”;
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), true);//true 显示控制器注释
    });

    运行效果,已经显示出我们的注释

    .NET中的Swagger使用示例详解

    可以在控制器、参数、实体类增加注释后,再次运行都有显示

    .NET中的Swagger使用示例详解

    四、对接口进行分组

    1.在AddSwaggerGen、UseSwaggerUI分别添加如下信息

    例如

    options.SwaggerDoc(\”yw\”, new OpenApiInfo { Title = \”业务模块\”, Version = \”yw\” });
    options.SwaggerDoc(\”qt\”, new OpenApiInfo { Title = \”其他模块\”, Version = \”qt\” });

    例如

    c.SwaggerEndpoint(\”/swagger/v1/swagger.json\”, \”公共模块\”);//接口文档json文件
    c.SwaggerEndpoint(\”/swagger/yw/swagger.json\”, \”业务模块\”);
    c.SwaggerEndpoint(\”/swagger/qt/swagger.json\”, \”其他模块\”);
    c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);//接口不展开None

    2.在controller或者action上打上ApiExplorerSettings特性

    例如[ApiExplorerSettings(GroupName = "v1")]

    .NET中的Swagger使用示例详解

    总结

    有Sawwger有利于前后端开发人员接口的对接,调试,功能上挺丰富的,简单的写了以上几点

    到此这篇关于.NET中的Swagger使用的文章就介绍到这了,更多相关.NET Swagger使用内容请搜索悠久资源网以前的文章或继续浏览下面的相关文章希望大家以后多多支持悠久资源网!

    您可能感兴趣的文章:

    • Asp.net6.0 Swagger使用问题及解决过程
    • Asp.Net Core使用swagger生成api文档的完整步骤
    • asp.net core 3.0中使用swagger的方法与问题
    • Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解
    • .Net Core2.1 WebAPI新增Swagger插件详解
    • .NET Core利用swagger进行API接口文档管理的方法详解
    • Asp.net core WebApi 使用Swagger生成帮助页实例

    收藏 (0) 打赏

    感谢您的支持,我会继续努力的!

    打开微信/支付宝扫一扫,即可进行扫码打赏哦,分享从这里开始,精彩与您同在
    点赞 (0)

    悠久资源 ASP.NET .NET中的Swagger使用示例详解 https://www.u-9.cn/biancheng/aspnet/183014.html

    常见问题

    相关文章

    发表评论
    暂无评论
    官方客服团队

    为您解决烦忧 - 24小时在线 专业服务