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 权限,给接口加权限验证
Net Core3.1 添加 Swagger的更多相关文章
- .Net Core 分布式微服务框架 - Jimu 添加 Swagger 支持
系列文章 .Net Core 分布式微服务框架介绍 - Jimu .Net Core 分布式微服务框架 - Jimu 添加 Swagger 支持 一.前言 最近有空就优化 Jimu (一个基于.Net ...
- NetCoreAPI添加Swagger
public class Startup { public Startup(IConfiguration configuration) { Configuration = configuration; ...
- 如何通过注解方式给项目添加Swagger功能
在Java后端,每次开发一个新的接口后需要自测,此时可以借助Swagger功能很好地完成自测,下面将通过注解的方式来添加Swagger. (1)代码部分 package com.bien.edge; ...
- (7)ASP.NET Core3.1 Ocelot Swagger
1.前言 前端与后端的联系更多是通过API接口对接,API文档变成了前后端开发人员联系的纽带,开始变得越来越重要,而Swagger就是一款让你更好的书写规范API文档的框架.在Ocelot Swagg ...
- 由ASP.NET Core WebApi添加Swagger报错引发的探究
缘起 在使用ASP.NET Core进行WebApi项目开发的时候,相信很多人都会使用Swagger作为接口文档呈现工具.相信大家也用过或者了解过Swagger,这里咱们就不过多的介绍了.本篇文章记录 ...
- Core3.0中Swagger使用JWT
前言 学习ASP.NETCore,原链接 https://www.cnblogs.com/laozhang-is-phi/p/9511869.html 原教程是Core2.2,后期也升级到了Core3 ...
- dotnet webapi 中添加Swagger文档
首先添加"SwaggerGenerator": "1.1.0","SwaggerUi": "1.1.0" 需要注意的是这 ...
- .net core 添加 Swagger
1.新建一个Core项目 添加nuget包:Swashbuckle.AspNetCore 添加Startup文件: 先引用: using Swashbuckle.AspNetCore.Swagger; ...
- .Net WebApi 添加Swagger
前言 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远. 前端和后端的唯一联系,变成了API接口:API文档 ...
随机推荐
- class A<T>where T:new()是什么意思
这是C#泛型类声明的语法class A<T> 表示 A类接受某一种类型,泛型类型为T,需要运行时传入where表明了对类型变量T的约束关系.where T:new()指明了创建T的实例时应 ...
- 如何安装部署和优化Tomcat?(Tomcat部署和优化与压测,虚拟主机配置,Tomcat处理请求的过程)
文章目录 前言 一:Tomcat安装部署 1.1:Tomcat简介 1.2:Tomcat核心组件 1.3:Tomcat处理请求的过程 1.3.1:请求过程基本解释 1.3.2:请求过程详细解释 1.4 ...
- Python学习第十二课——json&pickle&XML模块&OS模块
json模块 import json dic={'name':'hanhan'} i=8 s='hello' l=[11,22] data=json.dumps(dic) #json.dumps() ...
- LeetCode简单题(二)
题目一: 给定一个数组 nums 和一个值 val,你需要原地移除所有数值等于 val 的元素,返回移除后数组的新长度. 不要使用额外的数组空间,你必须在原地修改输入数组并在使用 O(1) 额外空间的 ...
- TensorFlow样例一
假设原函数为 f(x) = 5x^2 + 3,为了估计出这个函数,定义参数未知的函数g(x, w) = w0 x^2 + w1 x + w2,现要找出适合的w使g(x, w) ≍ f(x).将这个问题 ...
- centos6.9下 svn 1.7.10版本 编译安装
svn安装推荐文章: 1. http://blog.51cto.com/myhat/786950 2. https://blog.csdn.net/test1280/article/det ...
- C++11常用特性介绍——nullptr关键字及用法
一.nullptr关键字及用法 1)NULL的二义性 void func(int) {} void func(int*) {} 当函数调用func(NULL)时会执行哪个函数呢? 先看C++对NULL ...
- 阿里云服务器Ubantu16.04升级python3.6
从ppa上下载下载python3.6 sudo apt-get install software-properties-common#使用 “add-apt-repository” 脚本添加 ppa ...
- Codeforces1307D. Cow and Fields
对于本题,最短路,考虑bfs,那么我们可以跑2次bfs,求出每个点到1与n的最短路,设为x_a, x_b,那我们可以把问题转换成max(min{x_a+y_b,x_b+y_a}+1)(x,y属于1到n ...
- centos6.5安装图形操作界面
yum -y install xorg-x11-fonts-Type1 #安装Xwindow yum -y groupinstall "X Window System" #安装GN ...