通过Swashbukle给DotNet Core Web API 增加自动文档功能
DotNet Core Web API给开发者提供了一个很好的框架来开发Restful的API。那么这些API接口该如何管理起来呢?Swagger是一个很好的选择,Swagger不需要开发者额外去维护接口文档,只要开发者的接口遵循Restful的规范,Swagger就会根据API接口生成文档。
对于前后端分离的开发模式,前后端开发者一般会先定义好接口,然后各自独立开发,后端开发者可以使用Swagger很快的生成没有业务逻辑的接口文档,接口返回的是Mock Data,这样前端开发人员就可以更早的开始调用接口,只要关注Swagger的接口文档是否有发生变化,尽早的发现错误,避免了前后端最后集成时,出现大问题。
后端开发者使用Swagger也可以很好的调试,Swagger提供了一个简单的UI界面,可以模拟简单的post,get,put 。功能没有curl或者postman强大,但是优势在于简单快捷,只要在swagger文档界面点点就可以。
这里要介绍的就是:Dotnet Core 2.0 下面的 Swashbukle.AspNetCore
Github地址: https://github.com/domaindrivendev/Swashbuckle.AspNetCore
这篇文章的源码:dotnet-core-sample 的 sample1中
1.首先创建一个dotnet core web api 项目,通过命令行输入
dotnet new webapi -name sample1
2. 然后下载Swashbuckle AspNetCore
dotnet add package Swashbuckle.AspNetCore
在VS 2017下面,通过 工具 -> Nuget 包管理器 -> 程序包管理控制台, 运行
Install-Package Swashbuckle.AspNetCore
注意:这里运行的是Install-Package Swashbuckle.AspNetCore 不是Install-Package Swashbuckle
3.在Startup.cs文件中,引入Swashbuckle
using Swashbuckle.AspNetCore.Swagger;
4.在Startup.cs文件中的ConfigureService方法中注册Swagger Generator
public void ConfigureServices(IServiceCollection services){services.AddMvc();services.AddSwaggerGen(config =>{config.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });});}
5. 在Configure方法中添加Swagger的中间件
public void Configure(IApplicationBuilder app, IHostingEnvironment env){ if (env.IsDevelopment()){app.UseDeveloperExceptionPage();}app.UseMvc();app.UseSwagger();}
6. 最后执行一下dotnet run或者F5,就可以直接运行项目了
dotnet run
默认情况下,可以通过http://localhost:5000/swagger/ 访问API接口文档
注意:要自动生成文档,对应Controller下的接口必须显示的指定用那种Http请求方式,POST,GET,PUT,DELETE
Swagger运行起来后,有时候需要针对项目进行一些简单的配置:
除了前面提到的 new Info { Title = "My API", Version = "v1" },Swashbukle还可以配置其他信息,具体可以参见OpenAPI Specification.
config.SwaggerDoc("v1", new Info{Title = "My API - V1",Version = "v1",Description = "A sample API to demo Swashbuckle",TermsOfService = "Knock yourself out",Contact = new Contact{Name = "Joe Developer",Email = "joe.developer@tempuri.org"},License = new License{Name = "Apache 2.0",Url = "http://www.apache.org/licenses/LICENSE-2.0.html"}} )
最后,如果要配置多个swagger文档,需要通知添加swagger generator和endpoint
config.SwaggerDoc("v2", new Info { Title = "My API - V2", Version = "v2" }); config.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
原文地址:http://www.cnblogs.com/unclechan/p/7508011.html
.NET社区新闻,深度好文,微信中搜索dotNET跨平台或扫描二维码关注
通过Swashbukle给DotNet Core Web API 增加自动文档功能相关推荐
- 1.1 WEB API 在帮助文档页面进行测试
这篇文章http://www.cnblogs.com/landeanfen/p/5210356.html写得比较详细, 我就挑简单的来说. 首先用这功能要在WEB API创建的帮助文档下面,如果你使用 ...
- .NET Core Web API上为CORS启用OPTIONS标头
在dotnet core web api中支持CORS(跨域访问) 问题描述: 需要提前设置好cors,设置好cors后,get或者post(pain/text)这些简单类型都可以请求. 但是, 需要 ...
- ASP.NET Core Web API基于RESTFul APIs的集合结果过滤和分页
译者荐语:如何在RESTFul APIs中进行集合结果分页?还是用客户端来拼接链接地址么? 原文来自互联网,由长沙DotNET技术社区[邹溪源]翻译.如译文侵犯您的版权,请联系小编,小编将在24小时内 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- 循序渐进学.Net Core Web Api开发系列【7】:项目发布到CentOS7
系列目录 循序渐进学.Net Core Web Api开发系列目录 本系列涉及到的源码下载地址:https://github.com/seabluescn/Blog_WebApi 一.概述 本篇讨论如 ...
- 如何测试ASP.NET Core Web API
在本文中,我们将研究如何测试你的ASP .NET Core 2.0 Web API解决方案.我们将了解使用单元测试进行内部测试,使用全新的ASP .NET Core的集成测试框架来进行外部测试. 本文 ...
- 重温.NET下Assembly的加载过程 ASP.NET Core Web API下事件驱动型架构的实现(三):基于RabbitMQ的事件总线...
重温.NET下Assembly的加载过程 最近在工作中牵涉到了.NET下的一个古老的问题:Assembly的加载过程.虽然网上有很多文章介绍这部分内容,很多文章也是很久以前就已经出现了,但阅读之后发现 ...
- ASP.NET Core Web API使用静态swagger.json文件
前言 ASP.NET Core Web API默认集成了Swashbuckle,可以在运行时显示Swagger UI: 而Swagger UI实际上是解析的动态生成的swagger.json: app ...
- 如何测试 ASP.NET Core Web API
在本文中,我们将研究如何测试你的 ASP .NET Core 2.0 Web API 解决方案.我们将了解使用单元测试进行内部测试,使用全新的 ASP .NET Core 的集成测试框架来进行外部测试 ...
最新文章
- JVM 内存优化设置
- 部分知名公司的网址 合集
- C# 依据KeyEventArgs与组合键字符串相互转换
- 现有代码移植到Metro App
- [转] VS2010中VC9.0Runtime与VC10.0Runtime在win7上装不上提示error code 1603
- 一个寄存器有几个字节_STM32f103ZET6 学习资料 (连载2 寄存器的操作界限)
- 时域频域与傅立叶变换
- 软件架构设计——软件架构风格
- css easyui,对比easyui和jwwui css
- 虚拟机中部署ISA Server 2006 防火墙 网络设置(上)
- 【Spring 核心】装配Bean(一) 自动化装配
- 利用AJAX技术实现网页无刷新进度条显示
- 思维导图与知识树的区别
- java多态的练习 ,定义三个类,父类GeometricObject代表几何形状,子类Circle代表圆形,MyRectangle代表矩形。 定义一个测试类GeometricTest,编写equals
- 当电脑打开显示每日新闻联播主要内容
- 8月9日华为发布了其自研的鸿蒙操作系统,华为正式发布自研操作系统鸿蒙
- zoho在线文档使用小技巧
- java企业物流管理系统 (JSP物流公司管理系统毕业设计)
- 罗克韦尔CompactLogix 控制系统PLC如何借助工业网关实现远程编程维护?
- C语言实现简易商城交易功能