Net Core3.1 添加 Swagger
一、为什么使用Swagger
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
没有API文档工具之前，大家都是手写API文档的，在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏。
书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。
二、配置Swagger服务
1、建一个net Core 3.1 的API项目，不演示了都会
2、引用Nuget包
右键项目中的 依赖项 -- > 管理 Nuget 程序包 --> 浏览 --> 搜索"Swashbuckle.AspNetCore" --> Install 安装最新版
安装完成后在项目的Nuget依赖里看到刚刚引入的Swagger
3、配置服务
打开Startup.cs类，编辑ConfigureServices方法
// This method gets called by the runtime. Use this method to add services to the container. public void ConfigureServices(IServiceCollection services) { services.AddControllers(); #region swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" }); }); #endregion }
3、启动Http中间件
编辑Configure方法
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { //判断是否是环境变量 if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } #region swagger app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); }); #endregion app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
4、查看效果
到这，已经完成swagger的添加，F5 运行调试，在域名后面输入/swagger，例如：http://localhost:54067/swagger/index.html 点击回车，就出来了
5、设置默认直接首页访问 —— 生产环境
每次手动在域名后边输入 /swagger ，很麻烦！
swagger 给我们提供了这个扩展，我们可以指定一个空字符，作为 swagger 的地址，在Configure中配置中间件：
#region swagger app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); c.RoutePrefix = "";//路径配置，设置为空，表示直接访问该文件，表示直接在根域名（localhost:8001）访问该文件 //这个时候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉， 然后直接访问localhost:8001/index.html即可 }); #endregion
然后再把我们上边的项目文件 launchSettings.json 的 launchUrl 给去掉就行了，这样我们无论是本地开发环境，还是生产环境，都可以默认首页加载了。
这时候会发现没有注释，如果有注释可读性就很好了，下面开始实现注释
6、显示注释
1、给接口加一个注释
/// <summary> /// ID 获取Json列表 /// </summary> /// <param name="id"></param> /// <returns></returns> [HttpGet("{id}")] public IEnumerable<WeatherForecast> Get(int id)
2、右键点击项目---->属性------>生成------>勾选xml文档文件
3、在startup类中的ConfigureServices 方法中的服务集合中添加如下代码
#region swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" }); var basePath = AppContext.BaseDirectory; var xmlPath = Path.Combine(basePath, "Blog.Core.xml"); c.IncludeXmlComments(xmlPath, true); //添加控制器层注释（true表示显示控制器注释） }); #endregion
4、运行项目并访问swaggerUI
可以显示注释了
7、对 Model 也添加注释说明
新建一个.net core 类库Blog.Core.Model，注意是 .net core的类库，或者使用标准库也是可以的！（标准库可以在 NetCore 和 Framework 两个项目都可以跑）
然后新建一个model
/// <summary> /// 这是爱 /// </summary> public class Love { /// <summary> /// id /// </summary> public int Id { get; set; } /// <summary> /// 姓名 /// </summary> public string Name { get; set; } /// <summary> /// 年龄 /// </summary> public int Age { get; set; } }
1、当前 api 层直接引用了 Blog.Core.Model 层；
2、Blog.Core.Model 右键属性配置 xml
3、导入model.xml到swagger
// This method gets called by the runtime. Use this method to add services to the container. public void ConfigureServices(IServiceCollection services) { services.AddControllers(); #region swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" }); var basePath = AppContext.BaseDirectory; var xmlPath = Path.Combine(basePath, "Blog.Core.xml"); c.IncludeXmlComments(xmlPath, true); //添加控制器层注释（true表示显示控制器注释） var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml"); c.IncludeXmlComments(xmlModelPath, true); }); #endregion }
接口添加注释
/// <summary> /// post /// </summary> /// <param name="love">model 实体类</param> [HttpPost] public void Post(Love love) { }
重新运行就出来了
8、隐藏某些接口
如果不想显示某些接口，直接在controller 上，或者action 上，增加特性
[ApiExplorerSettings(IgnoreApi = true)]
/// <summary> /// post /// </summary> /// <param name="love">model 实体类</param> [HttpPost] [ApiExplorerSettings(IgnoreApi =true)] public void Post(Love love) { }
Post方法就不显示了
三、结语
下一篇 Swagger JWT 权限，给接口加权限验证
