Core + Vue 后台管理基础框架8——Swagger文档
1、前言
作为前后端分离的项目,或者说但凡涉及到对外服务的后端,一个自描述,跟代码实时同步的文档是极其重要的。说到这儿,想起了几年前在XX速运,每天写完代码,还要给APP团队更新文档的惨痛经历。给人家普及swagger,说不习惯,就要手写的Word文档。
闲话少扯。一份合格的文档,最起码要包括rest地址,HTTP方法,入参出参,入参出参的描述,如果接口包括授权,swagger文档还需要对应包括这部分的处理。做到这点,前端团队必定会感激你的,而且一个靠谱的前端,它也一定会要求你这么做的。再闲扯一句,我曾听一位同事说,搞.NET的,前端后端全栈一把梭,要毛的文档。。。我仔细回想了下早几年,好像.NETer确实全栈比较多,所谓的人少事儿多高效钱少。。。
2、实现
(1)添加Swashbuckle.AspNetCore包引用
(2)Startup工程下添加如下项目特性
简单交代下,上边一行代表生成控制器及操作方法xml描述文档,下边一句是说没有描述时候,VS编译不生成警告信息。
(3)Dto工程同上
(4)Swagger相关服务注册
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "System Management", Version = "v1" }); c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Name = "Authorization",
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer",
BearerFormat = "JWT",
In = ParameterLocation.Header,
Description = "JWT Authorization header using the Bearer scheme."
});
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] {}
}
}); c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SystemManagement.Dto.xml"));
});
c.SwaggerDoc("v1", new OpenApiInfo { Title = "System Management", Version = "v1" });这句代表文档的版本,标题等信息;
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme)这部分代表告诉swagger,系统是采用bearer token认证的,方便swagger在页面上提供
token入口,同时交代了使用JWT这种token;
c.AddSecurityRequirement(new OpenApiSecurityRequirement)这部分则是告诉swagger全局应用上述认证模式;
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SystemManagement.Dto.xml"));
最后边这两句include则是告诉swagger描述文档中元数据从何而来。第(2)步中我们设置项目属性之后,xml文档就会自动生成并输出到系统根目录。 (5)swagger中间件引入
app.UseSwagger(); app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "System Management V1");
c.RoutePrefix = string.Empty;
});
c.RoutePrefix = string.Empty;这句是为了让swagger文档直接挂在系统跟路径上。 3、效果
启动后端访问http://localhost:5000,如下:
我们以获取用户个人信息为例,走swagger调用下:
因为没有token嘛,自然就401了。好,那我们走登录接口,取一个合法token(登录是不需要认证的,所以可以直接走swagger调用):
拿到其中的token值,然后到swagger文档顶部去认证:
提供了JWT,现在我们再从swagger调用获取个人信息接口:
可以看到,已经成功调用接口了。既然前言部分我们说到了接口自描述,那我们就来看看,文档是否做到了自描述。
如上, rest终结点有了,接口地址有了,接口描述也有了。此方法没有入参,所以看不到入参,那我们看出参或者返回结果,是一样的:
结果信息描述,也有了。是不是比手撸接口文档,或者MD文档,要舒服、省事儿得多?
Core + Vue 后台管理基础框架8——Swagger文档的更多相关文章
- Core + Vue 后台管理基础框架0——开篇
1.背景 最近,打算新开个项目,鉴于团队技术栈,选型.net core + vue,前后端分离.本打算捡现成的轮子的,github上大致逛了逛,总发现这样那样的不太适合心中那些“完美实践”,例如:Ab ...
- Core + Vue 后台管理基础框架4——前端授权
1.前言 上篇,我们讲了后端的授权.与后端不同,前端主要是通过功能入口如菜单.按钮的显隐来控制授权的.具体来讲,就是根据指定用户的制定权限来加载对应侧边栏菜单和页面内的功能按钮.我们一个个来讲. 2. ...
- Core + Vue 后台管理基础框架2——认证
1.前言 这块儿当时在IdentityServer4和JWT之间犹豫了一下,后来考虑到现状,出于3个原因,暂时放弃了IdentityServer4选择了JWT: (1)目前这个前端框架更适配JWT: ...
- Core + Vue 后台管理基础框架3——后端授权
1.前言 但凡业务系统,授权是绕不开的一环.见过太多只在前端做菜单及按钮显隐控制,但后端裸奔的,觉着前端看不到,系统就安全,掩耳盗铃也好,自欺欺人也罢,这里不做评论.在.NET CORE中,也见过不少 ...
- Core + Vue 后台管理基础框架9——统一日志
1.背景 前阵子有园友留言,提到日志相关的东西,同时,最近圈子里也有提到日志这个东西.一个充分.集中的统一日志平台还是很有必要的,否则系统出问题了只能靠猜或者干瞪眼.何谓充分,日志记录满足最低要求.出 ...
- Core + Vue 后台管理基础框架1——运行系统
1.down源码 git clone https://github.com/KINGGUOKUN/SystemManagement.git,项目目录如下: 2.还原数据库 找到项目根目录下System ...
- Core + Vue 后台管理基础框架7——APM
1.前言 APM,又称应用性能统计,主要用来跟踪请求调用链,每个环节调用耗时,为我们诊断系统性能.定位系统问题提供了极大便利.本系统采用的是Elastic Stack体系中的APM,主要是之前部门搞P ...
- hsweb 企业后台管理基础框架
hsweb 详细介绍 业务功能 现在: 权限管理: 权限资源-角色-用户. 配置管理: kv结构,自定义配置.可通过此功能配置数据字典. 脚本管理: 动态脚本,支持javascript,groovy, ...
- 基于bootstrap的漂亮网站后台管理界面框架汇总
基于bootstrap的漂亮网站后台管理界面框架汇总 10个最新的 Bootstrap 3 管理模板 这里分享的 10 个模板是从最新的 Bootstrap 3 管理模板集合中挑选出来的,可以帮助你用 ...
随机推荐
- Docker学习笔记_04 Rancher的部署安装(编排选用K8S)
原文地址:http://dbase.cc/2018/01/12/docker/04_rancher的部署安装/ 为什么要使用Rancher Rancher是一个开源的企业级容器管理平台.通过Ranch ...
- Java Servlet和Java Filter简介
一:简介servlet 1.什么是Servlet? Servlet可以通过多种方式进行描述,具体取决于上下文: (1)Servlet是一种用于创建web应用程序的技术 (2)Servlet是一个API ...
- 吴裕雄--天生自然 python开发学习笔记:pycharm无法使用ctrl+c/v复制粘贴的问题
在使用pycharm的时候发现不能正常使用ctrl+c/v进行复制粘贴,也无法使用tab键对大段代码进行整体缩进.后来发现是因为安装了vim插件的问题,在setting里找到vim插件,取消勾选即可解 ...
- React.js/HTML5和iOS双向通信
最近,我使用WKWebView和React.js进行双向通信,自己写了React.js嵌入到Native中. Native操作Web,通过两种方式传值 第一种,通过JS传值给Native 通过这种方式 ...
- python 爬虫保存文件的几种方法
import os os.makedirs('./img/', exist_ok=True) IMAGE_URL = "https://morvanzhou.github.io/static ...
- Redis:slave flush old data造成实例不可用
一.问题描述 2019-02-22凌晨02:42分前后,收到集群中 [10.32.52.8:6500] 实例不可用告警,登陆管理界面查看此实例在正常运行状态,期间未出现机器宕机或实例直接挂掉的现象. ...
- C++扬帆远航——12(抓小偷)
/* * Copyright (c) 2016,烟台大学计算机与控制工程学院 * All rights reserved. * 文件名:zhaoxiaotou.cpp * 作者:常轩 * 微信公众号: ...
- Git私服搭建
Git私服搭建 一.Git服务器搭建方式 GIT是一个分布式版本管理系统,既然是分布那么必定会涉及远程通信,那么GIT是采用什么协议进行远程通信? Git支持的四种通信协议: Local(本地协议) ...
- Chrome 插件安装时报错: "CRX_HEADER_INVALID"
1. 将 crx 插件后缀名改为 rar 2. 解压 rar 包 3. 进入浏览器 1). 点击Chrome浏览器地址栏最右边的三个点 --> 更多工具 --> 扩展插件 --> 点 ...
- Ios/Android h5 唤起本地APP
纠结两天(浏览器中唤起本地APP),一直找不到解决方案,今天总算基本搞定. ps:吐槽一下 魔窗那篇文章,为什么就不直接把js代码开源开源,混淆后的代码看得我好恼火 参考文章:魔窗解决方案.京东解决方 ...