正文

本文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. Navicat Premium连接mongodb基本使用和介绍

    Navicat premium是一款数据库管理工具,是一个可多重连线资料库的管理工具, 它可以让你以单一程式同时连线到 MySQL.SQLite.Oracle 及 PostgreSQL,mongodb ...

  2. Microsemi Libero系列教程(一)——Libero开发环境介绍、下载、安装与注册

    前言 相比与Xilinx和Altera在国内的市场,Microsemi的FPGA在国内应用很少很少,网上几乎没有详细的教程,刚开始使用时,遇到了各种问题,自己也走了不少弯路.本系列教程以Libero ...

  3. 母版页 treeview控件 SiteMapPath控件 treeview数据库绑定模式

     母版页就是网站中一样的部分母版页的后缀名是.Master可以把母版页当成一个页面  想让哪里是别的内容就可以  通过如下: <asp:ContentPlaceHolder ID="C ...

  4. C#函数(构造函数)的重载

    using System; namespace test { class Program { static void Main(string[] args) { Cat cat = new Cat() ...

  5. Geohash精度和原理

    转自:https://blog.csdn.net/u011497262/article/details/81210634 https://www.jianshu.com/p/1ecf03293b9a ...

  6. Selenium模块的安装

    Selenium模块 1.安装selenium python2:pip install selenium python3:pip install selenium 2.设置浏览器驱动 解压后必须与浏览 ...

  7. Scrapy框架的简单使用

    一.安装依赖 #Windows平台 1.pip3 install wheel 3.pip3 install lxml 4.pip3 install pyopenssl 5.pip3 install p ...

  8. requests-html库render的使用

    一.render的使用 from requests_html import HTMLSession session =HTMLSession() response = session.get('htt ...

  9. ios11下适配UItableView

    参考链接: https://www.cnblogs.com/spider-pei/p/7592906.html

  10. 中文版 Apple 官方 Swift 教程《The Swift Programming Language》

    简介 欢迎使用 Swift 关于 Swift 版本兼容性 Swift 初见 Swift 版本历史记录 Swift 教程 基础部分 基本运算符 字符串和字符 集合类型 控制流 函数 闭包 枚举 类和结构 ...