.NET Core使用swagger进行API接口文档管理
一、问题背景
随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了API接口,但是目前项目中对于API的管理很多时候还是通过手工编写文档,每次的需求变更只要涉及到接口的变更,文档都需要进行额外的维护,如果有哪个小伙伴忘记维护,很多时候就会造成一连续的问题,那如何可以更方便的解决API的沟通问题?Swagger给我们提供了一个方式,由于目前主要我是投入在.NET Core项目的开发中,所以以.NET Core作为示例
二、什么是Swagger
Swagger可以从不同的代码中,根据注释生成API信息,swagger拥有强大的社区,并且对于各种语言都支持良好,有很多的工具可以通过swagger生成的文件生成API文档
三、.NET Core中使用
.NET Core中使用首先要用nuget引用Swashbuckle.AspNetCore,在startup.cs中加入如下代码
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "WebApplication2.xml");
c.IncludeXmlComments(xmlPath);
});
services.AddMvcCore().AddApiExplorer();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseMvcWithDefaultRoute();
app.UseSwagger(c =>
{
});
app.UseSwaggerUI(c =>
{
c.ShowExtensions();
c.ValidatorUrl(null);
c.SwaggerEndpoint("/swagger/v1/swagger.json", "test V1");
});
}
以上部分为加载swagger的代码,位于startup.cs中,下面是controller代码:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
namespace WebApplication2.Controllers
{
/// <summary>
/// 测试信息
/// </summary>
[Route("api/[controller]/[action]")]
public class ValuesController : Controller
{
/// <summary>
/// 获取所有信息
/// </summary>
/// <returns></returns>
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
/// <summary>
/// 根据ID获取信息
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
// GET api/values/5
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
/// <summary>
/// POST了一个数据信息
/// </summary>
/// <param name="value"></param>
// POST api/values
[HttpPost]
public void Post([FromBody]string value)
{
}
/// <summary>
/// 根据ID put 数据
/// </summary>
/// <param name="id"></param>
/// <param name="value"></param>
// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, [FromBody]string value)
{
}
/// <summary>
/// 根据ID删除数据
/// </summary>
/// <param name="id"></param>
// DELETE api/values/5
[HttpDelete("{id}")]
public void Delete(int id)
{
}
/// <summary>
/// 复杂数据操作
/// </summary>
/// <param name="id"></param>
// DELETE api/values/5
[HttpPost]
public namevalue test(namevalue _info)
{
return _info;
}
}
public class namevalue
{
/// <summary>
/// name的信息
/// </summary>
public String name { get; set; }
/// <summary>
/// value的信息
/// </summary>
public String value { get; set; }
}
}
接下来我们还需要在生成中勾上XML生成文档,如图所示
接下去我们可以运行起来了,调试,浏览器中输入http://localhost:50510/swagger/,这里端口啥的根据实际情况来,运行效果如下图所示:
可以看到swagger将方法上的注释以及实体的注释都抓出来了,并且显示在swaggerui,整体一目了然,并且可以通过try it按钮进行简单的调试,但是在具体项目中,可能存在需要将某些客户端信息通过header带到服务中,例如token信息,用户信息等(我们项目中就需要header中带上token传递到后端),那针对于这种情况要如何实现呢?可以看下面的做法
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "WebApplication2.xml");
c.IncludeXmlComments(xmlPath);
c.OperationFilter<AddAuthTokenHeaderParameter>();
});
services.AddMvcCore().AddApiExplorer();
}
public class AddAuthTokenHeaderParameter : IOperationFilter
{
public void Apply(Operation operation, OperationFilterContext context)
{
if (operation.Parameters == null)
{
operation.Parameters = new List<IParameter>();
}
operation.Parameters.Add(new NonBodyParameter()
{
Name = "token",
In = "header",
Type = "string",
Description = "token认证信息",
Required = true
});
}
}
我们在ConfigureServices添加了OperationFilter<AddAuthTokenHeaderParameter>(),通过这种方式我们可以在swagger中显示token的header,并且进行调试(如图所示),AddAuthTokenHeaderParameter 的apply的属性context中带了controller以及action的各种信息,可以配合实际情况使用
四、与其他API管理工具结合
swagger强大的功能以及社区的力量,目前很多的API管理工具都支持YApi,目前我们使用的是由去哪儿开源的YApi,从图中可以看到YApi支持导入swagger生成的JSON文件,除该工具 之外DOClever(开源)也是一个不错的API管理工具,也支持Swagger文件导入(具体工具用法,大家可以去看他们的官网)
五、总结
Swagger是一个很好的工具,并且在前后端分离开发越来越流行的情况下,在后续的开发过程中,我觉得会扮演着越来越重要的作用,目前我们公司小的项目已经准备开始使用swagger+yapi进行API的管理方式,而这篇文章也是这段时间抽空整理API管理的结果,希望可以帮助到大家,这里可能有很多不足的地方,欢迎大家拍砖,也希望可以跟大家一起进步
原文地址: https://www.cnblogs.com/OMango/p/8460092.html
.NET社区新闻,深度好文,欢迎访问公众号文章汇总 http://www.csharpkit.com
.NET Core使用swagger进行API接口文档管理相关推荐
- 盘点 8 款好用的 API 接口文档管理工具
随着互联网的普及和发展,API 接口已经无处不在.它已经在 Web 应用程序.移动应用程序.云计算.物联网.人工智能等领域中得到广泛应用. 例如,在金融行业中,API 接口可以被用于构建支付服务.银行 ...
- 一款强大的API接口文档管理工具(Smart-Doc + Torna)
[本文由龙飞同学供稿] 在团队协作开发项目的时候,接口文档承担着向其他开发人员说明接口相关信息的重要任务,因此,一份清晰而又相近的接口文档至关重要. 但是,写接口文档的痛苦想必各位开发人员都体验过,明 ...
- Spring Cloud Zuul中使用Swagger汇总API接口文档
有很多读者问过这样的一个问题: 虽然使用Swagger可以为Spring MVC编写的接口生成了API文档,但是在微服务化之后,这些API文档都离散在各个微服务中,是否有办法将这些接口都整合到一个文档 ...
- Spring Cloud Zuul中使用Swagger汇总API接口文档 1
有很多读者问过这样的一个问题:虽然使用Swagger可以为Spring MVC编写的接口生成了API文档,但是在微服务化之后,这些API文档都离散在各个微服务中,是否有办法将这些接口都整合到一个文档中 ...
- 在线ajax测试,在线测试 - SosoApi,简单强大的api接口文档管理平台
背景: 在实际项目开发协同过程中,特别是前后端由不同开发人员开发时,前端接口联调必须要等后端接口开发完成后才可以.这种方式使得前端极大的依赖 于后端,使得原本可以并行的工作被阻塞了,特别是流程性质的功 ...
- django rest framework 使用api接口文档
django rest framework 使用api接口文档 一.使用swagger生成api接口文档 二.使用drf自带的api接口文档 三.drf-yasg 一.使用swagger生成api接口 ...
- 引入swagger2 api接口文档并实现离线文档
文章目录 前言 目的 导入工具 写一个config类 启动类添加注解 试启动页面 补充并实现文档 特殊点 再次启动页面 导出swagger在线文档为离线文档 忽略SSL证书 前言 本篇文章在于介绍sw ...
- php怎么根据接口文档实现功能,CodeIgniter+swagger实现 PHP API接口文档自动生成功能...
一.安装swagger 1.首先需要有composer,没有的自行百度安装 2.下载swagger,打开网站https://packagist.org/packages/zircote/swagger ...
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
Swagger是一个描述RESTful的Web API的规范和框架.如果使用ASP.NET的话,可以用Swashbuckle来自动生成Swagger,具体参考如何使 WebAPI 自动生成漂亮又实用在 ...
最新文章
- Docker 入门系列(2)- Docker 镜像, 免 sudo 使用 docker 命令、获取查看、修改镜像标签、查找删除创建镜像、导入导出镜像
- 如何在系统崩溃时从C++中获取函数调用栈信息?
- R语言ggplot2可视化分面图(faceting)、编写自定义函数将生成的分面图分裂成多个子图、并按照索引读取对应的可视化图像:Split facet plot into list of plots
- 把激光雷达放在iPad上是怎样的体验?看到“测距仪”App的效果我震惊了
- 知识图谱资源-NLP
- ODT .NET 详解之 SqlDataSource 访问 Oracle
- 代数学笔记10.1: 关于对称多项式的理解和三次预解式的推导
- linq 获取实体列表中的某个字段返回iliststring
- 连设计图都不会画,你还想做“系统架构师”?
- mysql 数据库连接不够_一个Web报表项目的性能分析和优化实践(二):MySQL数据库连接不够用(TooManyConnections)问题的一次分析和解决案例...
- Convert your single instance to 10g RAC by manual
- 高清成主流 十大最受用户关注摄像头
- DFS POJ 1321 棋盘问题
- hello语音为什连接不上服务器,Hello语音交友怎么玩_Hello语音交友打不开
- 使用mybatis的分页插件和Thymeleaf实现分页效果
- 微软 2021 校园招聘正式启动!
- windows电脑使用iTunes导入视频/音乐(本人使用,仅供参考)
- PC和DSP通信以及MCU和DSP通信之间的切换
- python自学免费图片_自学Python----爬取Beautyleg图片
- 亚马逊儿童背包 CPSIA,CSPA邻苯二甲酸盐和镉 CPC测试
热门文章
- 拒绝“高冷”词汇!初学C#中的委托
- oracle sqlplus使用
- CentOS7安装EPEL源
- 《HTML5触摸界面设计与开发》——1.4 神秘谷,是什么让触摸界面反应灵敏?...
- Angular 2 Decorators - 1
- 一个简单的MVC模式练习
- Oracle hang 之sqlplus -prelim使用方法
- (译)Windsor入门教程---第三部分 编写第一个Installer
- ueditor 编辑器再thinkphp中使用 解决转义问题
- [活动 3.30]MAUI 跨平台应用开发实战