.net core 使用swagger自动生成接口文档
前言
swagger是一个api文档自动生动工具,还集成了在线调试. 可以为项目自动生成接口文档, 非常的方便快捷
Swashbuckle.AspNetCore 是一个开源项目,用于生成 ASP.NET Core Web API 的 Swagger 文档. 本文采用这个!
一. 利用nuget添加引用 swashbuckle.AspNetCore
注意.net core 3.0需要引用 swashbuckle.AspNetCore 5.0 以上, 由于目前(2019/12/12)nuget 上最新的是4.0.1 所以要手动添加
地址 https://www.nuget.org/packages/Swashbuckle.AspNetCore
二. 在 Startup.cs 里面注册服务,添加中间件
添加引用
using Swashbuckle.AspNetCore.Swagger;
注册服务
public void ConfigureServices(IServiceCollection services)
{
//注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });//设置版本号,标题
var xmlPath = Path.Combine(Path.GetDirectoryName(typeof(Program).Assembly.Location), "SwaggerApi.xml");// 为 Swagger JSON and UI设置xml文档注释路径
c.IncludeXmlComments(xmlPath);//只有设置了xmlm文档的路径生成的文档才会有注释
});
services.AddMvc();
}
注意..net core 3.0这里有个改动, 使用这个代码
//注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });// .net core 3.0
//c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });//设置版本号,标题 .net core 2.0
var xmlPath = Path.Combine(Path.GetDirectoryName(typeof(Program).Assembly.Location), "SwaggerApi.xml");// 为 Swagger JSON and UI设置xml文档注释路径
c.IncludeXmlComments(xmlPath);//只有设置了xmlm文档的路径生成的文档才会有注释
});
添加中间件
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
//启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui,指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseMvc();
}
三. 修改项目属性
1. 在生成的输入里面勾选 XML文档文件, 并将文件名更改为注册服务的定义的文件名,地址建议改为相对地址
2. 可以选择隐藏1591的错误提示,不隐藏所有没有写注释的地方都会有警告
3. 如果有多个项目,需要在注册服务时新增一个xml文件路由,并在另一个项目里也修改项目属性
4. 修改生成的xml文件的属性,将"复制到输出目录"改为"始终复制"
四. 写接口调试
1. 创建返回实体, 要想接口中自带注释说明,实体必须要写上注释
/// <summary>
/// 返回实体
/// </summary>
public class TestResult
{
/// <summary>
/// 用户Id
/// </summary>
public string Id;
/// <summary>
/// 用户名称
/// </summary>
public string Name;
}
2. 写接口
需要注意action的路由,请求方式,返回类型,都要加上,否则会导致文档不全
/// <summary>
/// 测试接口
/// </summary>
/// <param name="id">用户Id</param>
/// <returns></returns>
[Route("api/[controller]/[action]")]
[HttpGet]
[ProducesResponseType(typeof(TestResult), )]
public IActionResult Test(string id)
{
return Ok(new TestResult
{
Id = id,
Name = "Hello World"
});
}
五. 查看结果
https://localhost:xxxx/swagger/index.html
展开
六. 在线调试 点击 Try It Out
填写参数
结果
七. 添加头部参数
1. 新增OperationFilter的实现
public class SwaggerHeaderFilterr : IOperationFilter
{
/// <summary>
/// swagger新增头部参数
/// </summary>
/// <param name="operation"></param>
/// <param name="context"></param>
public void Apply(Operation operation, OperationFilterContext context)
{
var headers = new Dictionary<string, string> { { "appkey", "分配的AppKey" }, { "randomcode", "随机码" }, { "timestamp", "时间戳(秒数)" }, { "sign", "签名" } };
foreach (var item in headers)
{
operation.Parameters.Add(new NonBodyParameter()
{
Name = item.Key,
In = "header",//query header body path formData
Type = "string",
Description = item.Value,
Required = false //是否必选
});
}
} }
2. 在AddSwaggerGen中添加
OperationFilter<SwaggerHeaderFilterr>();
3. 查看结果
注:
1. 如何修改首页的路由
.net core 使用swagger自动生成接口文档的更多相关文章
- Asp.Net Core 轻松学-利用 Swagger 自动生成接口文档
前言 目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对于开发人员来说,编写接口文档 ...
- Asp.Net Core 轻松学系列-5利用 Swagger 自动生成接口文档
目录 前言 结语 源码下载 前言 目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对 ...
- springboot结合swagger自动生成接口文档
前后台分离的开发渐渐已成趋势.那么前后端的沟通就成了问题,包括移动端,web端.如果有一个东西在我们写完代码的时候,自动将接口的所有注释,调用文档提供出来,是不是一件很美好的事情.那就是使用swagg ...
- Swagger自动生成接口文档
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://mave ...
- WebApi使用swagger ui自动生成接口文档
之前就写到.最近正在使用webapi.这里介绍一个实用的东西swageer ui现在开发都是前后端分开.我们这里是给前端提供api.有时候对于一个api的描述,并不想专门写一份文档.很浪费时间.swa ...
- Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
- go实践之swagger自动生成api文档
文章目录 go实践之swagger自动生成api文档 1.安装需要用到的包 2.接口代码支持swagger 3. 生成swagger接口 go实践之swagger自动生成api文档 作为一个后端开发, ...
- Spring Boot Swagger2自动生成接口文档
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 1.问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 2 ...
- Django框架深入了解_05 (Django中的缓存、Django解决跨域流程(非简单请求,简单请求)、自动生成接口文档)
一.Django中的缓存: 前戏: 在动态网站中,用户所有的请求,服务器都会去数据库中进行相应的增,删,查,改,渲染模板,执行业务逻辑,最后生成用户看到的页面. 当一个网站的用户访问量很大的时候,每一 ...
随机推荐
- Java基础 -- 深入理解迭代器
在Java基础 -- 持有对象(容器)已经详细介绍到,集合(Collection)的种类有很多种,比如ArrayList.LinkedList.HashSet.... 由于集合的内部结构不同,很多时候 ...
- 经典面试题-python函数之默认参数
1.可变的默认参数----list 示例: def add(a, mylist=[]): # print(id(mylist)) mylist.append(a) return mylist pri ...
- 课下作业MyCP的分析
目录 MyCP 题目 截图 代码 相关知识 出现的问题 代码托管 参考资料 MyCP 题目 编写MyCP.java 实现类似Linux下cp XXX1 XXX2的功能,要求MyCP支持两个参数: ja ...
- CTF--web 攻防世界web题 robots backup
攻防世界web题 robots https://adworld.xctf.org.cn/task/answer?type=web&number=3&grade=0&id=506 ...
- Markdown——入门指南
导语: Markdown 是一种轻量级的「标记语言」,它的优点很多,目前也被越来越多的写作爱好者,撰稿者广泛使用.看到这里请不要被「标记」.「语言」所迷惑,Markdown 的语法十分简单.常用的标记 ...
- npm install 时出现的 EACCES: permission denied 错误的可能有效的解决方案
最近我开始接触手机 app 的编写,公司用到了 Nativescript.当我下载了公司的项目后,在配置时出现了不少的问题,其中出现概率最高的就是 EACCES: permission denied ...
- 转载:在做datatable时候查询数据和条数只用一次sql就可以解决需求
前言:最近用datatable处理数据比较多,所以在使用时候想提升性能 select * from t_hr_leave SELECT FOUND_ROWS() //返回查询记录的总数 select ...
- Python——各类库的安装(持续更新)
一.BeautifulSoup 说明:www.crummy.com:Beautiful Soup 3只能在python2.x版本中运行,而Beautiful Soup 4还可以在python3.x版本 ...
- 记我在github上参与的Star增长最快的十万级项目。。。
前言 GitHub作为程序员的圣地. 用了两三年,一直都觉得,他可以代码托管,项目管理,为项目建立静态主页,个人简历,找工作,面试加分. 然而>>>....昨天才认识到我还是太年轻, ...
- http 状态码大全
状态码大全 1**(信息类):表示接收到请求并且继续处理 100——客户必须继续发出请求 101——客户要求服务器根据请求转换HTTP协议版本 2**(响应成功):表示动作被成功接收.理 ...