• .Net Core 3.1浏览器后端服务(三) Swagger引入与应用


    一、前言

    前后端分离的软件开发方式已逐步成为互联网项目开发的业界标准,前后端分离带来了诸多好处的同时,也带来了一些弊端。

    接口文档的维护就是其中之一,起初前后端约定文档规范,开发的很愉快,随着时间推移、版本迭代、接口更改,接口文档维护越来越麻烦。

    相信很多前端开发者(请求方)都遇到过实际请求与接口文档不一致的问题

    后端开发者(接口提供方)因为时间问题经常来不及更新。
    所以仅仅只通过强制来规范大家是不够的,此时Swagger应运而生

    什么是Swagger?

    Swagger是一个强大的接口文档自动生成工具。

    二、引入Swagger包

    在Package Manager Console输入如下命令

    Install-Package Swashbuckle.AspNetCore -Version 6.0.7

    或者在MWebAPI项目右键

     

    选择最新版本Install,安装完成后添加Swagger服务注入及中间件配置

    在Startup类的ConfigureServices方法中添加服务注入:

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo {Title = "Net Core API", Version = "v1"});
    });

    在Startup类的Configure方法中配置Swagger相关中间件:

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Net Core API");
    });

    F5运行项目

     咦,Swagger文档并未展示,这是由于默认启动url未更改

    修改launchSetting.json文件中launchUrl如下:

     再次F5运行

    预想的SwaggerUI展示出来了

    三、添加注释

    1、首先添加文档说明及作者信息

    修改Swagger服务注入部分

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "Net Core API",
            Version = "v1",
            Description = "A simple DotNet core web API sample program",
            Contact = new OpenApiContact
            {
                Name = "Sirius",
                Email = "1247830052@qq.com",
                Url = new Uri("https://www.cnblogs.com/mchao/"),
                Extensions = null,
            },
            License = new OpenApiLicense
            {
                Name = "免费许可",
                Url = new Uri("https://www.cnblogs.com/mchao/"),
                Extensions = null,
            }
        });
    });

     运行如下:

    2、添加生成Controller的注释说明

    MWebAPI项目右键->properties->build->output

     build项目会生成Controller.xml文件及内容(自动创建更新,无需手动维护)

    接着在AddSwaggerGen方法中添加文档路径

    services.AddSwaggerGen(c =>
    {var xmlPath = Path.Combine(AppContext.BaseDirectory, "Controller.xml");
        c.IncludeXmlComments(xmlPath, true);
    });

    运行如下:

     3、添加返回数据的注释说明

    MDto项目右键->properties->build->output

    接着在AddSwaggerGen方法中添加文档路径

    services.AddSwaggerGen(c =>
    {
        var xmlDtoPath = Path.Combine(AppContext.BaseDirectory, "Dto.xml");
        c.IncludeXmlComments(xmlDtoPath, true);
    });

    运行

    这里有个异常,找不到Dto.xml,目前是这样处理的,Dto.xml文件属性 Copy to Outup Direcotry,如哪位道友有其他方案请告知。。。

     再次运行

     可看到Dto的注释信息

    四、Api分组

    1、增加分组

    在Startup类的ConfigureServices方法中增加doc分组:

    c.SwaggerDoc("V2", new OpenApiInfo
    {
        Title = "Net Core API V2",
        Version = "V2",
        Description = "A simple DotNet core web API sample program2",
    });

    在Startup类的Configure方法中增加v2 json路径

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/V1/swagger.json", "API V1");
        c.SwaggerEndpoint("/swagger/V2/swagger.json", "API V2");
    });

    2、配置分组

    给UserInfoController配置V1组

    [ApiExplorerSettings(GroupName = "V1")]
    public class UserInfoController : Controller

    给HomeController配置V2组

    [ApiExplorerSettings(GroupName = "V2")]
    public class HomeController : Controller

    运行:

    五、结语

    Swagger还有很多好用功能,比如自定义Swagger模板、Swagger开启权限验证等,希望感兴趣的道友继续探索!!!

    天行健,君子以自强不息; 地势坤,君子以厚德载物;
  • 相关阅读:
    通过字符串调用函数
    First,FirstOrDefault和Single,SingleOrDefault 的区别
    asp循环例子
    将il文件和资源文件生成dll工具
    C# 修改资源文件工具ResourceNet4
    北京ip
    实验1、Mininet 源码安装和可视化拓扑工具
    实验2:Mininet 实验——拓扑的命令脚本生成
    ajax post data 获取不到数据,注意 contenttype的设置 、post/get
    调试提示:当前不会命中断点
  • 原文地址:https://www.cnblogs.com/mchao/p/14411647.html
Copyright © 2020-2023  润新知