驾一叶之扁舟 举匏樽以相属
寄蜉蝣于天地,渺沧海之一粟。哀吾生之须臾,羡长江之无穷。
挟飞仙以遨游,抱明月而长终。知不可乎骤得,托遗响于悲风。

从壹开始前后端分离【 .NET Core2.0/3.0 +Vue2.0 】框架之三 || Swagger的使用 3.1

本文3.0版本文章

https://mp.weixin.qq.com/s/SHNNQoYF-t8i2j85E1oSYA

 

 

常见问题

 

1、Bug调试

群里有小伙伴反馈,在Swagger使用的时候报错,无法看到列表,这里我说下如何调试和主要问题:

1、如果遇到问题,这样的:

 

请在浏览器 =》 F12 ==》 console 控制台 ==》点击错误信息地址

或者直接链接http://localhost:xxxxx/swagger/v1/swagger.json,就能看到错误了

 

 

2、经常有小伙伴遇到这个错误

 

 

这是因为接口json文档定义和调用不是一个

1、定义:

ConfigureServices 方法中的  services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1", 

2、调用:

Configure 方法中的 app.UseSwaggerUI(c =>   调用  c.SwaggerEndpoint("/swagger/v1/swagger.js;

看看两者是否一致

 

 

3、路由重载

 

 

这种错误是因为路由过载了,请注意,是路由的过载,意思就是说,写了两个一样的路由,从而导致异常了,而不是说我们的方法一样,举例子:

可能你在 valuecontroller 里写了一个  Test1() 和 Test2() ,虽然方法名不一样,但是如果你的路由规范是 /api/[controller] 的话,那映射出来的路由,两个都是 api/value ,所以就会报过载异常,

这个时候我们就需要修改一下,要么把谓词不一样,比如一个get,一个post,要么修改路由规则 /api/[controller]/[action]。

详细的知识点,请看官网。

 

 

 


一、为什么使用Swagger

上文中已经说到,单纯的项目接口在前后端开发人员使用是特别不舒服的,那所有要推荐一个,既方便又美观的接口文档说明框架,当当当,就是Swagger,随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 

前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。

没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。

书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。 

 

二、配置Swagger服务

1、引用Nuget包

下面开始引入swagger插件

方法有两个:

1)可以去swagger官网或github上下载源码,然后将源码(一个类库)引入自己的项目;

2)直接利用NuGet包添加程序集应用(这里就是前边说的 在以后的开发中,Nuget无处不在)。

右键项目中的 Dependencies -- > Manage Nuget Packags --> Browse --> Search "Swashbuckle.AspNetCore" --> Install

 

 

然后就在项目的Nuget依赖里看到刚刚引入的Swagger

 


图 2

这个时候,你可以试一下,当然是不可以的,还记得上文说的,.Net Core 都需要一个程序入口么,对就是Startup.cs文件

 

2、配置服务

打开Startup.cs类,编辑ConfigureServices类

     public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v0.1.0",
                    Title = "Blog.Core API",
                    Description = "框架说明文档",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                });
            });

            #endregion

        }

 

3、启动Http中间件

编辑Configure类

    // 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();
            }

            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
            });
            #endregion

            app.UseMvc();
        }

 

4、查看效果

到这,已经完成swagger的添加,F5 运行调试,在域名后面输入/swagger,http://localhost:54067/swagger/index.html 点击回车,当当当 出来啦

 

5、好像少点儿什么?!

 

在上边的截图中,我们可以看到,已经生成了一个 api 列表,我们不仅可以清晰的看到项目中含有那些接口,还可以直接点击发送请求,类似 postman 那样,做接口调试,
但是现在有两个问题:
1、这个接口文档现在还不多,如果多了的话,每个接口对应的意义可能会混淆,
2、另外,这个接口文档,也是方便前端工程师查看的,目前这个这个样式,看起来是挺费解的。
 
这个时候,要是有一个注释功能就很好了,别着急,看看下边的截图,是不是你想要的效果?!

 

既美观又快捷,而且还有丰富的注释,这样以后发布出去,前后端开发人员就可以一起开发了,嗯!不错!

那这个注释功能,应该这么做呢?下一篇文章就会说到了。

 

三、结语

  好啦,本节基本就是这里了,你简单浏览后,会了解到,什么是Swagger,它如何创建使用,如何运行的,但是,细心的你会发现一些问题:

如何直接F5运行,首页无法加载?

接口虽有,但是没有文字文档说明?

对于接口是如何加权限验证的?

如何发布到服务器,大家一起接口开发呢?

项目开发中的实体类是如何在Swagger中展示的?

让我们带着这些问题,继续浏览下一篇吧,Swagger 3.2 配置

ღ 网友反馈ღ

@BlueDr提出:可以将Swagger的UI页面配置在Configure的开发环境之中

       public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                #region Swagger
                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
                });
                #endregion
            }


            app.UseMvc();
        }

 

 

四、Github && Gitee

https://github.com/anjoy8/Blog.Core.git

https://gitee.com/laozhangIsPhi/Blog.Core

posted @ 2018-08-17 22:53  老张的哲学  阅读(24896)  评论(35编辑  收藏
作者:老张的哲学
好好学习,天天向上
返回顶部小火箭
好友榜:
如果愿意,把你的博客地址放这里
jianshu.com/u/老张
SqlSugar codeisbug.com