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文档的更多相关文章

  1. Core + Vue 后台管理基础框架0——开篇

    1.背景 最近,打算新开个项目,鉴于团队技术栈,选型.net core + vue,前后端分离.本打算捡现成的轮子的,github上大致逛了逛,总发现这样那样的不太适合心中那些“完美实践”,例如:Ab ...

  2. Core + Vue 后台管理基础框架4——前端授权

    1.前言 上篇,我们讲了后端的授权.与后端不同,前端主要是通过功能入口如菜单.按钮的显隐来控制授权的.具体来讲,就是根据指定用户的制定权限来加载对应侧边栏菜单和页面内的功能按钮.我们一个个来讲. 2. ...

  3. Core + Vue 后台管理基础框架2——认证

    1.前言 这块儿当时在IdentityServer4和JWT之间犹豫了一下,后来考虑到现状,出于3个原因,暂时放弃了IdentityServer4选择了JWT: (1)目前这个前端框架更适配JWT: ...

  4. Core + Vue 后台管理基础框架3——后端授权

    1.前言 但凡业务系统,授权是绕不开的一环.见过太多只在前端做菜单及按钮显隐控制,但后端裸奔的,觉着前端看不到,系统就安全,掩耳盗铃也好,自欺欺人也罢,这里不做评论.在.NET CORE中,也见过不少 ...

  5. Core + Vue 后台管理基础框架9——统一日志

    1.背景 前阵子有园友留言,提到日志相关的东西,同时,最近圈子里也有提到日志这个东西.一个充分.集中的统一日志平台还是很有必要的,否则系统出问题了只能靠猜或者干瞪眼.何谓充分,日志记录满足最低要求.出 ...

  6. Core + Vue 后台管理基础框架1——运行系统

    1.down源码 git clone https://github.com/KINGGUOKUN/SystemManagement.git,项目目录如下: 2.还原数据库 找到项目根目录下System ...

  7. Core + Vue 后台管理基础框架7——APM

    1.前言 APM,又称应用性能统计,主要用来跟踪请求调用链,每个环节调用耗时,为我们诊断系统性能.定位系统问题提供了极大便利.本系统采用的是Elastic Stack体系中的APM,主要是之前部门搞P ...

  8. hsweb 企业后台管理基础框架

    hsweb 详细介绍 业务功能 现在: 权限管理: 权限资源-角色-用户. 配置管理: kv结构,自定义配置.可通过此功能配置数据字典. 脚本管理: 动态脚本,支持javascript,groovy, ...

  9. 基于bootstrap的漂亮网站后台管理界面框架汇总

    基于bootstrap的漂亮网站后台管理界面框架汇总 10个最新的 Bootstrap 3 管理模板 这里分享的 10 个模板是从最新的 Bootstrap 3 管理模板集合中挑选出来的,可以帮助你用 ...

随机推荐

  1. CentOS7下MySQL5.7的安装-RPM方式

    Installing MySQL on Linux Using RPM Packages 下载安装包 mysql下载地址:https://dev.mysql.com/downloads/mysql/ ...

  2. js中的call

    //例1 <script> window.color = 'red'; document.color = 'yellow'; var s1 = {color: 'blue' }; func ...

  3. c++入门资源

    http://www.cnblogs.com/jackyyang7/articles/2479482.htmlvs2010编译器的使用 https://www.cnblogs.com/me115/ar ...

  4. vue项目实战

    本篇文章主要介绍了vue的环境配置,vue项目的目录结构以及在开发vue项目中问题的一些解决方案. 环境配置及目录结构 1.安装node.js(http://www.runoob.com/nodejs ...

  5. Hexo之旅(四):文章编写技巧

    hexo 编写文章可以使用以下命令创建hexo new "文件名" #创建的文章会在_pots目录下文章的后缀名是以md命名的文件格式,遵循markdown语法,所以编写文章可以使 ...

  6. IP 多播

    IP 多播 一.IP 多播的基本概念 1.1.简介 不使用多播时需要发送 90 次单播: 使用多播时只需要发送 1 次多播: 1.2.IP 多播的一些特点 多播使用组地址:D 类IP地址支持多播.多播 ...

  7. USB小白学习之路(7) FPGA Communication with PC by CY7C68013,TD_init()解析

    注:这个TD_Init()只对EP6进行了配置,将其配置成为Bluk_In端口,而没有对EP2进行配置.这篇文章直接把寄存器的图片贴上来了,看起来比较杂.感兴趣的可以看下一篇文章,是转自CSDN,对E ...

  8. 【WPF学习】第五十一章 动画缓动

    线性动画的一个缺点是,它通常让人觉得很机械且不能够自然.相比而言,高级的用户界面具有模拟真实世界系统的动画效果.例如,可能使用具有触觉的下压按钮,当单击时按钮快速弹回,但是当没有进行操作时它们会慢慢地 ...

  9. 关于Markdown下无法使用表格的解决方案

    关于Markdown下无法使用表格的解决方案 写表格,出现如下场景 解决方法.点击左下角M的表示,切换到extra模式 打开了新世界.如果不能点击,估计是你没有激活pro的权限,百度下就可以了. 或者 ...

  10. 基于Blazor写一个简单的五子棋游戏

    写这个五子棋游戏,其实主要目的是想尝试一下微软新作Blazor.Blazor对于那些搞.NET的程序员,又想做一些前端工作,真的挺友好,不用一句JS就可搞定前端交互,美哉.现在已经有很流行的前端框架, ...