.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的理解和記錄,如果有問題的地方煩請大佬指出,萬分感謝!