.NET中的Swagger使用示例详解_Asp.net

前言

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

一、swagger是什么？

swagger (openapi) 是一个与语言无关的规范，用于描述 rest api。

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

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

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

二、如何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.运行效果

如图（示例）：

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

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

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

 app.useswagger();
    app.useswaggerui(c => { 
        c.documenttitle = "后台接口列表";   //标签页标题
        c.swaggerendpoint("/swagger/v1/swagger.json", "公共模块");//接口文档json文件
        c.routeprefix =string.empty;// 注:这里的路由修改后，launchsettings.json中的launchurl对应需要调整为""
    });

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

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

如何添加接口的注释呢

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 显示控制器注释
});

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

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

四、对接口进行分组

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