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. 推荐使用concurrent包中的Atomic类

        这是一个真实案例,曾经惹出硕大风波,故事的起因却很简单,就是需要实现一个简单的计数器,每次取值然后加1,于是就有了下面这段代码:           private int counter = ...

  2. Pandas写excel总结:写入多个sheet、1个sheet写入多行、向已有sheet追加数据

    1.最简单最基础的写:1excel1sheet df.to_excel("test.xlxs") 2.在一个excel文件里面写入多个sheet writer=pd.ExcelWr ...

  3. 吴裕雄--天生自然python编程:实例(3)

    # 返回 x 在 arr 中的索引,如果不存在返回 -1 def binarySearch (arr, l, r, x): # 基本判断 if r >= l: mid = int(l + (r ...

  4. struts2和springmvc性能比较2

    我们用struts2时采用的传统的配置文件的方式,并没有使用传说中的0配置.spring3 mvc可以认为已经100%零配置了(除了配置spring mvc-servlet.xml外). Spring ...

  5. HBase完全分布式集群搭建

    HBase完全分布式集群搭建 hbase和hadoop一样也分为单机版,伪分布式版和完全分布式集群版,此文介绍如何搭建完全分布式集群环境搭建.hbase依赖于hadoop环境,搭建habase之前首先 ...

  6. 吴裕雄--天生自然 PHP开发学习:PhpStorm的配置与安装

    下载安装包

  7. 《HelloGitHub》第 47 期

    兴趣是最好的老师,HelloGitHub 就是帮你找到兴趣! 简介 分享 GitHub 上有趣.入门级的开源项目. 这是一个面向编程新手.热爱编程.对开源社区感兴趣 人群的月刊,月刊的内容包括:各种编 ...

  8. 2、【Spark】Spark环境搭建(集群方式)

    Spark集群方式搭建结构如图所示,按照主从方式.

  9. NumPy的随机函数子库——numpy.random

    NumPy的随机函数子库numpy.random 导入模块:import numpy as np 1.numpy.random.rand(d0,d1,...,dn) 生成一个shape为(d0,d1, ...

  10. 编写一个可复用的SpringBoot应用运维脚本

    前提 作为Java开发者,很多场景下会使用SpringBoot开发Web应用,目前微服务主流SpringCloud全家桶也是基于SpringBoot搭建的.SpringBoot应用部署到服务器上,需要 ...