在webapi中使用swagger

Posted 2021-01-05 露似真珠月似弓

1 在webapi项目下安装swagger，包名 Swashbuckle.AspNetCore

2 在webapi的startup.cs文件中添加swagger服务

/// <summary>
        /// 配置服务 注册服务
        /// </summary>
        /// <param name="services"></param>
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v0.1.0",
                    Title = "学习Swagger",
                    Description = "框架说明文档",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Learn.Swagger", Email = "[e-mail]", Url = "https://www.facai.com" }
                });
                //如果不加入以下两个xml 也是可以的 但是不会对api有中文说明，使用了一下两个xml 就需要对成员使用///注释
                //本webapi的xml
                var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "Learn.Swagger.xml");//这个就是刚刚配置的xml文件名
                c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改


                //如果不引用别的类库项目，那么以上就是一个webapi项目添加swagger服务的全部


                //webapi引用model的xml 
                var xmlModelPath = Path.Combine(basePath, "Learn.Swagger.Model.xml");//这个就是Model层的xml文件名
                c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
                c.IncludeXmlComments(xmlModelPath);
            });

            #endregion

        }

 

3 在中间件代码块中添加 Swagger中间件

 

 // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        /// <summary>
        /// 配置中间件
        /// </summary>
        /// <param name="app"></param>
        /// <param name="env"></param>
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();

                #region Swagger
                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
                });
                #endregion
            }


            app.UseMvc();
        }

 4.要配合我们第二步中的xml，我们要对webapi项目做如下操作

 右键webapi项目属性——生成——勾选 XML文档文件 如下图:

如果引用了类库项目 也要勾选类库项目的XML文档文件，然后被webapi项目引用。

 5.让webapi启动调试自动展示swagger接口信息页面

上面4步完成后 要输入 localhost:接口/swagger 这个地址才能看到接口信息页面

为了默认启动时 localhost:接口 页面直接打开接口信息页面 可以在 launchSettings.json 页面进行配置

修改如下:

 大功告成！