欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

ASP.NET Core 2.2 WebApi 系列【四】集成Swagger

程序员文章站 2022-06-13 07:54:31
Swagger 是一款自动生成在线接口文档+功能测试功能软件 一、安装程序包 通过管理 NuGet 程序包安装,搜索Swashbuckle.AspNetCore 二、配置 Swagger 将 Swagger 添加到 Startup.ConfigureServices 方法中的服务集合中: //注入S ......

swagger

是一款自动生成在线接口文档+功能测试功能软件

一、安装程序包

通过管理 nuget 程序包安装,搜索swashbuckle.aspnetcore

ASP.NET Core 2.2 WebApi 系列【四】集成Swagger

二、配置 swagger

将 swagger 添加到 startup.configureservices 方法中的服务集合中:

            //注入swagger服务
            services.addswaggergen(c =>
            {
                    c.swaggerdoc("v1", new info { title = "my api", version = "v1" });
            });

在 startup.configure 方法中,启用中间件为生成的 json 文档和 swagger ui 提供服务

            //启用swagger服务
            app.useswagger();
            app.useswaggerui(c =>
            {
                c.swaggerendpoint("/swagger/v1/swagger.json", "my api v1");
                c.defaultmodelsexpanddepth(-1); //设置为 - 1 可不显示models
                c.docexpansion(docexpansion.none); //设置为none可折叠所有方法
            });

 

运行项目,可在 http://localhost:<port>/swagger 浏览 api文档,如下所示:

ASP.NET Core 2.2 WebApi 系列【四】集成Swagger

如果想把swagger作为启动页面,可修改launchsettings.json,把  launchurl设置为  swagger:

    "iis express": {
      "commandname": "iisexpress",
      "launchbrowser": true, //是否在浏览器中启动
      "launchurl": "swagger", //在浏览器中启动的相对url
      "environmentvariables": { //将环境变量设置为键/值对
        "aspnetcore_environment": "development"
      }

 

所有的controller 的方法都是可以在 ui 上面进行测试。点击方法可以展开对应的区域,点击【try it out】→ 【输入参数】→ 点击【execute】。

三、可扩展性

swagger 文档信息和描述

修改addswaggergen 方法,用来添加文档信息。例如:作者,版权,描述。

            services.addswaggergen(option =>
            {
                option.swaggerdoc("v1", new info
                {
                    version = "v1",
                    title = "在线接口文档",
                    description = "一个简单的例子",
                    contact = new contact { name = "tenghao", email = "tenghao510@qq.com" },
                    license = new license { name = "博客地址", url = "https://www.cnblogs.com/tenghao510/" }
                });
            });

 

下图展示了 swagger ui 显示添加的版本信息。

ASP.NET Core 2.2 WebApi 系列【四】集成Swagger

xml注释

【右键项目】→【属性】→ 【生成】→ 【勾选xml 文档文件】注意自己的路径

ASP.NET Core 2.2 WebApi 系列【四】集成Swagger

修改addswaggergen 方法。

备注:includexmlcomments方法中的includecontrollerxmlcomments参数控制是否显示控制器注释,默认是false。

            services.addswaggergen(c =>
            {
                c.swaggerdoc("v1", new info
                {
                    version = "v1",
                    title = "在线接口文档",
                    description = "一个简单的例子",
                    contact = new contact { name = "tenghao", email = "tenghao510@qq.com" },
                    license = new license { name = "tenghao", url = "https://www.cnblogs.com/tenghao510/" }
                });
                // 为 swagger json and ui设置xml文档注释路径
                var basepath = path.getdirectoryname(typeof(program).assembly.location);//获取应用程序所在目录
                var xmlpath01 = path.combine(basepath, "netcorewebapi.xml");
                c.includexmlcomments(xmlpath01, true);
                var xmlpath = path.combine(basepath, "netcorewebapi.model.xml");
                c.includexmlcomments(xmlpath);
            });

 

运行项目,再看看效果:

ASP.NET Core 2.2 WebApi 系列【四】集成Swagger