正文

本文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

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

  1. Z从壹开始前后端分离【 .NET Core2.0/3.0 +Vue2.0 】框架之十 || AOP面向切面编程浅解析:简单日志记录 + 服务切面缓存

    本文梯子 本文3.0版本文章 代码已上传Github+Gitee,文末有地址 大神反馈: 零.今天完成的深红色部分 一.AOP 之 实现日志记录(服务层) 1.定义服务接口与实现类 2.在API层中添 ...

  2. Z从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之七 || API项目整体搭建 6.2 轻量级ORM

    本文梯子 本文3.0版本文章 前言 零.今天完成的蓝色部分 0.创建实体模型与数据库 1.实体模型 2.创建数据库 一.在 IRepository 层设计接口 二.在 Repository 层实现相应 ...

  3. Z从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之六 || API项目整体搭建 6.1 仓储+服务+抽象接口模式

    本文梯子 本文3.0版本文章 前言 零.完成图中的粉色部分 2019-08-30:关于仓储的相关话题 一.创建实体Model数据层 二.设计仓储接口与其实现类 三.设计服务接口与其实现类 四.创建 C ...

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

    本文梯子 本文3.0版本文章 前言 一.swagger的一般用法 0.设置swagger页面为首页——开发环境 1.设置默认直接首页访问 —— 生产环境 2.为接口添加注释 3.对 Model 也添加 ...

  5. Z从壹开始前后端分离【 .NET Core2.0/3.0 +Vue2.0 】框架之二 || 后端项目搭建

    本文梯子 前言 1..net core 框架性能测试 2..net core 执行过程 3.中间件执行过程 4.AOP切面 5.整体框架结构与数据库表UML 一.创建第一个Core 1.SDK 安装 ...

  6. Z从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之五 || Swagger的使用 3.3 JWT权限验证【必看】

    本文梯子 本文3.0版本文章 前言 1.如何给接口实现权限验证? 零.生成 Token 令牌 一.JWT ——自定义中间件 0.Swagger中开启JWT服务 1:API接口授权策略 2.自定义认证之 ...

  7. Z从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之九 || 依赖注入IoC学习 + AOP界面编程初探

    本文梯子 本文3.0版本文章 更新 代码已上传Github+Gitee,文末有地址 零.今天完成的绿色部分 一.依赖注入的理解和思考 二.常见的IoC框架有哪些 1.Autofac+原生 2.三种注入 ...

  8. Z从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之八 || API项目整体搭建 6.3 异步泛型仓储+依赖注入初探

    本文梯子 本文3.0版本文章 回顾 1.Sqlsugar 的使用 2.修改数据连接字符串 今天要完成的浅紫色部分 一.设计仓储基类接口——IBaseRepository.cs 二.将其他的仓储接口,继 ...

  9. Z从壹开始前后端分离【 .NETCore2.1 +Vue 2 +AOP+DI】框架之一 || 前言

    老张 .NetCore与Vue 框架学习目录

随机推荐

  1. 秒懂:tomcat的maxConnections、maxThreads、acceptCount 图解

    后面附图 | 秒懂 疯狂创客圈 Java 高并发[ 亿级流量聊天室实战]实战系列 [博客园总入口 ] 前言 疯狂创客圈(笔者尼恩创建的高并发研习社群)Springcloud 高并发系列文章,将为大家介 ...

  2. aop分层模型——aop是元编程的一种

    织入应用层—->待织入的附加功能 应用层 织入管理层—->使用元语和织入的功能进行编程 语言层 aop元语层---〉aop机制提供的高阶抽象概念. 解释层 aop引擎层—->维护的实 ...

  3. 爬虫模拟有道字典进行翻译,还发现了一条好玩的js

    08.14自我总结 爬虫模拟有道字典进行翻译 一.代码 import requests from lxml.html import etree # headers= { # 'User-Agent': ...

  4. CRM第一篇

    2.1搭建前提 我们在搭建CRM开发环境之前,需要明确2件事情: a.我们搭建环境采用基于注解的配置. b.搭建环境需要测试,我们以客户的保存和列表查询作为测试功能. 2.2搭建步骤 2.2.1导入S ...

  5. 上传图片到七牛云(服务端 node.js sdk)

    大体思路 前端要上传图片到七牛云,需要有一个token进行授权操作,而获取这个上传的upload token(以下简称upToken),在服务端需要一定的身份校验,比如说:只有登录的vip用户才能拿到 ...

  6. apache部分报错解决方法

    AH00558: 进入apache文件夹下的conf文件夹,打开httpd.conf文件,用ctrl+F找到ServerName,如下图 在下面加上一句: ServerName domain_name ...

  7. Hacking/Penetrating tester bookmark collection

    Blogs http://carnal0wnage.blogspot.com/ http://www.mcgrewsecurity.com/ http://www.gnucitizen.org/blo ...

  8. Spring Boot 2 发布与调用REST服务

    开发环境:IntelliJ IDEA 2019.2.2Spring Boot版本:2.1.8 一.发布REST服务 1.IDEA新建一个名称为rest-server的Spring Boot项目 2.新 ...

  9. 个人项目-WC(C/C++ 兼容Linux和Windows)

    一.Github地址 https://github.com/S-TRAVELER/WC 实现的功能: 支持 -c 支持 -w 支持 -l 支持 -s 支持 -a 图形界面 多参数(文件名或通配符表达式 ...

  10. LinuxVIM编辑器用法

    vi编辑器是Linux系统下标准的编辑器.而且不逊色于其他任何最新的编辑器. 基本上vi可以分为三种状态,分别是命令模式(command mode).插入模式(Insert mode)和底行模式(la ...