.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实体

 1   public class Student
 2     {
 3 
 4         public int ID { get; set; }
 5         public string name { get; set; }
 6 
 7         public int age { get; set; }
 8 
 9         public string ClassName { get; set; }
10     }
11 }

5、IStudentService.cs,业务接口

1    public interface IStudentService : IApplicationService
2     {
3         /// <summary>
4         /// 根据ID获取学生
5         /// </summary>
6         /// <param name="id"></param>
7         /// <returns></returns>
8         Student GetStudentById(int id);
9     }

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

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

7、StudentController,应用层接口

 1  public static IStudentService _studentService;
 2         public StudentController(IStudentService service)
 3         {
 4             _studentService = service;
 5         }
 6         [HttpGet]
 7         public object Get()
 8         {
 9            return _studentService.GetStudentById(1);
10         }

8、Startup配置

 1  public class Startup
 2     {
 3         public Startup(IConfiguration configuration)
 4         {
 5             Configuration = configuration;
 6         }
 7 
 8         public IConfiguration Configuration { get; }
 9 
10         // This method gets called by the runtime. Use this method to add services to the container.
11         public void ConfigureServices(IServiceCollection services)
12         {
13             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
14             services.AddScoped<IStudentService, StudentService>();//注入接口
15             var basePath = AppContext.BaseDirectory;
16             var xmlPath = System.IO.Path.Combine(basePath, "CodeSwaggerApiDemo.xml");//Swagger接口说明文件,里面会包含接口说明和参数说明
17 //添加Swagger配置
18             services.AddSwaggerGen(c =>
19             {
20                 c.SwaggerDoc("v1", new Info { Title = "CodeSwaggerApiDemo WebApi", Version = "v1" });
21                 c.DocInclusionPredicate((docName, description) => true);
22                 if (System.IO.File.Exists(xmlPath)) c.IncludeXmlComments(xmlPath);
23 
24             });
25         }
26 
27         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
28         public void Configure(IApplicationBuilder app, IHostingEnvironment env)
29         {
30             if (env.IsDevelopment())
31             {
32                 app.UseDeveloperExceptionPage();
33             }
34             else
35             {
36                 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
37                 app.UseHsts();
38             }
39 
40             app.UseHttpsRedirection();
41             //添加配置,.json如果遇到运行报错,直接运行..../swagger.json可查看详细的错误信息
42             app.UseMvc();
43             app.UseSwagger();
44             app.UseSwaggerUI(c =>
45             {
46                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "CodeSwaggerApiDemo WebApi");
47             });
48         }
49     }

9、运行结果

列出接口目录

调用接口结果

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