NetCore集成swagger

1）、使用Nuget搜索并安装 Swashbuckle.AspNetCore

2）、在ConfigureServices()中注册swagger服务

//注册swagger服务
            services.AddSwaggerGen((s) =>
            {
                //唯一标识文档的URI友好名称
                s.SwaggerDoc("swaggerName", new OpenApiInfo()
                {
                    Title = "swagger集成配置测试",//（必填）申请的标题。
                    Version = "5.3.1",//（必填）版本号(这里直接写的是Swashbuckle.AspNetCore包的版本号,(有写 v1 的))
                    Description = "描述信息",//对应用程序的简短描述。
                    Contact = new OpenApiContact()//公开API的联系信息
                    {
                        Email = "[email protected]",
                        Name = "张三",
                        Extensions = null,
                        Url = null
                    },
                    License = new OpenApiLicense()//公开API的许可信息
                    {
                        Name = "张三",
                        Extensions = null,
                        Url = null
                    }
                });

                //添加中文注释 
                //拼接生成的XML文件路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
                //HomeController为当前程序集下的一个类（可自定义一个当前应用程序集下的一个类）[用于获取程序集名称]
                var commentsFileName = typeof(HomeController).Assembly.GetName().Name + ".XML";
                var xmlPath = Path.Combine(basePath, commentsFileName);
                s.IncludeXmlComments(xmlPath);

                s.DocInclusionPredicate((docName, description) => true);

            });

3）、在Configure()中使用swagger中间件

 //使用swagger中间件,并提供UI界面
            app.UseSwagger();
            app.UseSwaggerUI((s) =>
            {
                //注意：/swagger/唯一标识文档的URI友好名称/swagger.josn   
                s.SwaggerEndpoint("/swagger/swaggerName/swagger.json", "项目名称");


            });

必须和上面使用的唯一标识名称一致

4）、在第2步中的添加中文注释，还需配置生成注释的xml文件

(项目右键--------->属性-------->生成---------->(勾选)XML 文档文件)

5）、勾选输出 XML 文档文件后，发现只要没有标上注释的类或方法都会出现绿色波浪线的警告

此时，我们可以取消警告加上 ;1591 即可

6)、其动项目时，我们希望默认打开 swagger 的UI界面，而不是每次手动输入，所以我们可以配置默认输出页

到launchSettings.json配置文件中修改默认输出页即可

修改指定节点的属性值

7）、编写接口方法 （注意：使用 swagger 接口方法必须明确标注请求方式【常见的为：Get 、 Post 】）

 /// <summary>
        /// 获取张三的个人信息
        /// </summary>
        /// <returns></returns>
        [HttpPost]
        public JsonResult GetInfo()
        {
            return new JsonResult(new
            {
                name = "张三",
                sex = "男",
                age = "20"
            });
        }

        /// <summary>
        /// 计算a加b的和
        /// </summary>
        /// <param name="a">第一个数</param>
        /// <param name="b">第二个数</param>
        /// <returns>a加b的等式和</returns>
        [HttpGet]
        public string GetResult(double a, double b)
        {
            return string.Format($"{a}+{b}={a + b}");
        }

8）、运行项目，在运行前（可以先重新生成一下，输出 "项目名称.xml" 的注释文档【默认生成在项目的根目录下】）

9）、使用swagger测试接口

　9.1)、无参接口

执行结果

9.2）、带参接口

直接结果

猜你喜欢