WebApi写好之后,在线帮助文档以及能够在线调试的工具是专业化的表现,而Swagger毫无疑问是做Docs的最佳工具,自动生成每个Controller的接口说明,自动将参数解析成json,并且能够在线调试。

那么要讲Swagger应用到Asp.net Core中需要哪些步骤,填多少坑呢?

安装Swagger到项目
{
"dependencies": {
"Swashbuckle": "6.0.0-beta902",
........

或者直接通过NuGet界面来添加Swashbuckle,目前最新版本6.0.0-beta902

配置Swagger

1.startup.cs=>configureServices

//文档解析
services.AddSwaggerGen();
//非必须
services.ConfigureSwaggerGen(options =>
{
options.SingleApiVersion(new Info
{
Version = "v1",
Title = "UFX.Mall商城对接企业内部系统服务中间件接口说明文档"+Configuration.GetValue<string>("Customer"),
Description = "Based on Asp.net Core WebApi,Powered By 柚凡信息科技 www.cnunify.com"
});
});

2.startup.cs=>configure

//文档解析
app.UseSwagger();
app.UseSwaggerUi();

3.自动读取方法的描述信息

参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger

重点:如何自定义Swagger的UI

所有配置做完后,直接访问http://xxx/swagger/ui 即可看到接口的界面了

但是默认的swagger UI个人认为还是有点丑陋,部分细节处理不到位,swagger的所有资源文件都是嵌入型的,无法直接修改,虽然提供部分ui接口,但如何才能完全自定义UI呢?

swagger是前后端完全分离的项目,前端静态文件通过ajax,请求json数据,返回接口的解析显示到页面上,swagger-ui可以在git中找到:https://github.com/swagger-api/swagger-ui/

将swagger-ui下载到本地,然后将dist里的所有文件放在wwwroot->swagger->ui

然后配置让asp.net core自动读取wwwroot的真实路径。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
loggerFactory.AddDebug();
//配置NLog
loggerFactory.AddNLog();
env.ConfigureNLog("nlog.config"); app.UseApplicationInsightsRequestTelemetry(); app.UseApplicationInsightsExceptionTelemetry(); //异常处理中间件
app.UseMiddleware(typeof(ExceptionHandlerMiddleWare)); app.UseMvc(); // Enable static files middleware.
app.UseStaticFiles();
app.UseMvcWithDefaultRoute();
//文档解析
app.UseSwagger();
app.UseSwaggerUi();
}

这样,所有swagger文件都在本地了,想怎样自定义都可以,show一下修改过的UI

当webapi发布到服务器,访问的时候右下角swagger会有一个异常错误,要取消该错误,只需要将index.html里加入validatorUrl设置为null,取消对url的验证即可

            window.swaggerUi = new SwaggerUi({
url: url,
validatorUrl: null,
dom_id: "swagger-ui-container",

参考文档:http://stackoverflow.com/questions/27808804/swagger-ui-shows-error-validation-when-deployed

同时swagger还提供一个接口文档编辑器swagger-editor,可以方便的编辑swagger.json,编辑好了可以导出到工程中

http://editor.swagger.io/

Asp.net Core WebApi 使用Swagger做帮助文档,并且自定义Swagger的UI的更多相关文章

  1. 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (上篇)

    前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...

  2. 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

    前言 回顾上一篇文章<使用Swagger做Api文档 >,文中介绍了在.net core 3.1中,利用Swagger轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终 ...

  3. Asp.Net Core 使用Swashbuckle.AspNetCore 生成API文档

    详情参考:https://www.cnblogs.com/morang/p/9741511.html github地址:https://github.com/yimogit/moxy.blogs/tr ...

  4. Asp.net MVC WebApi项目的自动接口文档及测试功能打开方法

    https://blog.csdn.net/foren_whb/article/details/78866133

  5. Asp.Net Core WebApi (Swagger+EF Core/Code First)

    Swagger简介: Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能. ...

  6. ASP.NET Core WebApi使用Swagger生成api说明文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  7. ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介

    参考地址,官网:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view ...

  8. Asp.net core WebApi 使用Swagger生成帮助页

    最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...

  9. ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

随机推荐

  1. $(document).ready,$(window).load,window.onload区别和联系

    $(document).ready是在dom结构加载完毕就执行. $(window).load 等价于window.onload,必须等到页面内包括图片的所有元素加载完毕后才能执行. $(docume ...

  2. MVC 模型

    dbcontent var ALLALBUMS=from album in db.albums orderby album.title ascending select album; storeman ...

  3. Mysql 自动增长 重置

    重置 MySQL 自增列 AUTO_INCREMENT 初时值 注意, 使用以下任意方法都会将现有数据删除. 方法一: delete from tb1; ALTER TABLE tbl AUTO_IN ...

  4. URL vs. HTML 录制模式

    转自:http://blog.csdn.net/testing_is_believing/article/details/5274188 一般来说,如果是标准使用IE访问的B/S架构,应该使用HTML ...

  5. Codeforces Round #386 (Div. 2)

    迟到的一次比赛 最近状态很崩溃 网速很慢 然后前面五题看了都有打 但是 只有A B E 是过了的 是时候要反省一下 A.随便判断一下就好 最少的份数嘛 B.画出来之后是一下子左边一下子右边 打一个递归 ...

  6. requireJS的初步掌握(二)

    前面我们讲述了requireJS的一些认知和优点,==>http://www.cnblogs.com/wymbk/p/6366113.html 这章我们主要描述的是requireJS的一些常用的 ...

  7. Python把给定的列表转化成二叉树

    在LeetCode上做题时,有很多二叉树相关题目的测试数据是用列表给出的,提交的时候有时会出现一些数据通不过,这就需要在本地调试,因此需要使用列表来构建二叉树,方便自己调试.LeetCode上二叉树结 ...

  8. ASP.NET C# 实现实时用户在线

    public static class UserOnline { /// <summary> /// 获取或设置在线列表 /// </summary> public stati ...

  9. C# Excel导入数据

    表 表的创建脚本 CREATE TABLE [dbo].[TB_PROJECTS_New1]( , ) NOT NULL, ) NULL, ) NULL, , ) NULL, , ) NULL, , ...

  10. BZOJ3932: [CQOI2015]任务查询系统 主席树

    3932: [CQOI2015]任务查询系统 Time Limit: 20 Sec  Memory Limit: 512 MBSubmit: 4869  Solved: 1652[Submit][St ...