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. ubuntu-vnc

    Centos 中文gnome: 全新以最小化包安装了64位的CentOS6.3系统,作为本地的Web服务器使用,现记录全过程: 1.先安装X Window yum groupinstall " ...

  2. php生成唯一随机码

    最终使用: echo md5(time() . mt_rand(1,1000000)) //A:利用时间戳的方法 md5("admin"); // B:32位MD5加密 subst ...

  3. 161027、Java 中的 12 大要素及其他因素

    对于许多人来说,"原生云"和"应用程序的12要素"是同义词.本文的目的是说有很多的原生云只坚持了最初的12个因素.在大多数情况下,Java 能胜任这一任务.在本 ...

  4. 2016年10月29日 星期六 --出埃及记 Exodus 19:14

    2016年10月29日 星期六 --出埃及记 Exodus 19:14 After Moses had gone down the mountain to the people, he consecr ...

  5. .net通用权限框架B/S (五)--WEB(2)登录

    .net通用权限框架 登录成功将 1.登录用户id保存到session 2.保存权限到Dictionary<int,string>,然后将该对象保存到session中,以便后续页面使用 D ...

  6. 关于input输入框内设置小图标的问题

    其实很简单,只需要html和css就可以搞定啦 首先:<input class="layui-input" id="test1" placeholder= ...

  7. text/html &amp; text/plain的区别

    需要了解的概念 Content-Type:用于定义用户的浏览器或相关设备如何显示将要加载的数据,或者如何处理将要加载的数据 MIME:MIME类型就是设定某种扩展名的文件用一种应用程序来打开的方式类型 ...

  8. USB接口程序编写

    copy from http://blog.csdn.net/luckywang1103/article/details/12393889# HID是Human Interface Devices的缩 ...

  9. java版云笔记(一)

    云笔记项目 这个项目的sql文件,需求文档,需要的html文件,jar包都可以去下载,下载地址为:http://download.csdn.net/download/liveor_die/998584 ...

  10. [转] Spring Boot中Web应用的统一异常处理

    [From] http://blog.didispace.com/springbootexception/ 我们在做Web应用的时候,请求处理过程中发生错误是非常常见的情况.Spring Boot提供 ...