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. asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档

    asp.net core中使用Swashbuckle.AspNetCore(swagger)生成接口文档 Swashbuckle.AspNetCore:swagger的asp.net core实现 项 ...

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

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

  3. 在ASP.NET Core Web API上使用Swagger提供API文档

    我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...

  4. asp.net core webapi之跨域(Cors)访问

    这里说的跨域是指通过js在不同的域之间进行数据传输或通信,比如用ajax向一个不同的域请求数据,或者通过js获取页面中不同域的框架中(iframe)的数据.只要协议.域名.端口有任何一个不同,都被当作 ...

  5. ASP.NET Core WebAPI 开发-新建WebAPI项目

    ASP.NET Core WebAPI 开发-新建WebAPI项目, ASP.NET Core 1.0 RC2 即将发布,我们现在来学习一下 ASP.NET Core WebAPI开发. 网上已经有泄 ...

  6. Asp.Net Core WebApi学习笔记(四)-- Middleware

    Asp.Net Core WebApi学习笔记(四)-- Middleware 本文记录了Asp.Net管道模型和Asp.Net Core的Middleware模型的对比,并在上一篇的基础上增加Mid ...

  7. ASP.Net Core WebApi几种版本控制对比

    版本控制的好处: (1)助于及时推出功能, 而不会破坏现有系统. (2)它还可以帮助为选定的客户提供额外的功能. API 版本控制可以采用不同的方式进行控制,方法如下: (1)在 URL 中追加版本或 ...

  8. ASP.NET WebAPI使用Swagger生成测试文档

    ASP.NET WebAPI使用Swagger生成测试文档 SwaggerUI是一个简单的Restful API测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON配置显示API .项目 ...

  9. ASP.NET Core WebApi 返回统一格式参数(Json 中 Null 替换为空字符串)

    相关博文:ASP.NET Core WebApi 返回统一格式参数 业务场景: 统一返回格式参数中,如果包含 Null 值,调用方会不太好处理,需要替换为空字符串,示例: { "respon ...

随机推荐

  1. linux系统编程之进程(二):进程生命周期与PCB(进程控制块)

    本节目标: 进程状态变迁 进程控制块 进程创建 进程撤消 终止进程的五种方法 一,进程状态变迁 进程的三种基本状态 就绪(Ready)状态 当进程已分配到除CPU以外的所有必要的资源,只要获得处理机便 ...

  2. diff生成补丁与patch打补丁

    1.使用diff生成补丁: diff是Linux下的文件比较命令,参数这里就不说了,直接man一下就行了,不仅可以比较文件,也可以比较两个目录,并且可以将不同之处生成补丁文件,其实就是一种打补丁的命令 ...

  3. “神马”框架之LigerUI

    我曾经参与一个产品的研发,前端框架用的就是LigerUI,之前我也没有听过这个框架. 因为是项目期初设计就定下来用LigerUI,根据系统的功能前端页面有跟多丰富的表现,所以需要改进前端效果,这次发现 ...

  4. 谈谈javascript中的日期Date对象

    一.日期对象  在javascript中并没有日期型的数据类型,但是提供了一个日期对象可以操作日期和时间.  日期对象的创建:  new Date();二.将日期对象转换为字符串  将日期对象转换为字 ...

  5. wordpress对显示某分类目录的文章列表页时对单个文章显示字数限制和省略

    wordpress会在对应的此类列表页面模板中,遍历输出每篇文章的信息,缩略图,作者,正文,标题等, 输出具体的正文的部分 使用这样一句 <?php the_content(''); ?> ...

  6. Contains DuplicateII

    超时版: /*Contains Duplicate II Given an array of integers and an integer k, find out whether there the ...

  7. 3D分析之3D要素工具箱(转)

    来自:http://blog.csdn.net/kikitamoon/article/details/8193764 整理有关 ArcGIS 10.1 3D分析工具箱中,3D Feature 工具箱中 ...

  8. CSS 居中方法集锦(*******************************)

      记录收集纯CSS层面实现的水平.垂直居中方法可用于块级.行内快.内联元素以及文字图片等. 水平或垂直居中 1.1 text-align1.2 margin1.3 line-height1.4 pa ...

  9. 1013: [JSOI2008]球形空间产生器sphere

    很直观的一个gauss题: 用的是以前用过的一个模板: #include<cstdio> #include<algorithm> #include<cmath> # ...

  10. HDU-1036 Average is not Fast Enough!

    Average is not Fast Enough! http://acm.hdu.edu.cn/showproblem.php?pid=1036 Problem Description A rel ...