.net core webApi之文档描述Swagger

       前面和几位同事在做项目的时候用了前后端分离模式,前端用react,后端才用webApi接口的形式进行交互,但是在开发过程中,发现由于业务逻辑很多,导致有着几百个大量的接口需要提供接口说明文档,可以想象是一个多大的工作量,当时同事就搭建了接口说明描述插件Swagger来解决了这个问题。由于工作的原因一直没有自己实践,,恰好这两天又在群里面看到"晓晨Master的Swagger文章(https://www.cnblogs.com/stulzq/p/11007770.html)",就想着自己实践一下,按照自己的理解做一个学习记录。

一、对Swagger的理解

   1、 什么是Swagger

          目前的理解来看,就是接口说明描述文档。

   2、Swagger的好处

         1、节省了自己去写接口说明的工作量,并且描述更加清晰，易于调用接口方理解和使用。

         2、接口可以直接调试、测试,及时返回接口接口,排查问题

二、配置使用

 1、创建项目,这里只是为了配置简单得Swagger，并没有按照实际项目中去分应用层、逻辑层。。。。。来创建项目。

2、添加Swagger插件到项目中,可以使用"程序包管理器控制台",根据自己的需要,可以搜索插件版本进行安装。

Install-Package Swashbuckle.AspNetCore -Version 4.0.1

3、IApplicationService.cs 应用接口逻辑基类

DynamicWebApi是实现动态API的特性,需要安装Install-Package Panda.DynamicWebApi,此实例中并没有实际用到。

 [DynamicWebApi]
 public interface IApplicationService : IDynamicWebApi
 {
 }

 4、Model->Student.cs实体

  public class Student
    {

        public int ID { get; set; }
        public string name { get; set; }

        public int age { get; set; }

        public string ClassName { get; set; }
    }
}

5、IStudentService.cs,业务接口

   public interface IStudentService : IApplicationService
    {
        /// <summary>
        /// 根据ID获取学生
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        Student GetStudentById(int id);
    }

6、StudentService.cs，实现业务逻辑接口

 public class StudentService : IStudentService
    {
        [HttpGet("{id:int}")]
        public Student GetStudentById(int id)
        {
            return new Student() { ID = 1, age = 15, ClassName = "高一7班", name = "张三" };
        }
    }

7、StudentController,应用层接口

 public static IStudentService _studentService;
        public StudentController(IStudentService service)
        {
            _studentService = service;
        }
        [HttpGet]
        public object Get()
        {
           return _studentService.GetStudentById(1);
        }

8、Startup配置

 public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddScoped<IStudentService, StudentService>();//注入接口
            var basePath = AppContext.BaseDirectory;
            var xmlPath = System.IO.Path.Combine(basePath, "CodeSwaggerApiDemo.xml");//Swagger接口说明文件,里面会包含接口说明和参数说明
//添加Swagger配置
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "CodeSwaggerApiDemo WebApi", Version = "v1" });
                c.DocInclusionPredicate((docName, description) => true);
                if (System.IO.File.Exists(xmlPath)) c.IncludeXmlComments(xmlPath);

            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            //添加配置,.json如果遇到运行报错,直接运行..../swagger.json可查看详细的错误信息
            app.UseMvc();
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "CodeSwaggerApiDemo WebApi");
            });
        }
    }

9、运行结果(xxxxxx/swagger/index.html)

列出接口目录

调用接口结果

以上就是本人对Swagger的理解和记录,如果有问题的地方烦请大佬指出,万分感谢!