专栏首页销声匿迹Core + Vue 后台管理基础框架8——Swagger文档

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文档,要舒服、省事儿得多?

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 最近的项目之开篇

      有小半年没写博客了,今年以来,感觉格外忙,再者,这半年代码写得相对少,做项目管理、出差、琐事多了,实在是惭愧。Java、前端、SQL还撸了一些,.NET好少...

    guokun
  • FastDFS.Client操作文件服务器

    guokun
  • log4net配置与初始化

    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHand...

    guokun
  • 维基解密公开CIA机密文档追踪工具Scribbles源码(别名为“Snowden Stopper”)

    既今年三月初开始,维基解密披露了一系列CIA Vault7 文档。4月28日维基解密再度公开了该系列中名为 Scribbles 的相关文件及其源代码。Scrib...

    FB客服
  • 教你如何快速从 Oracle 官方文档中获取需要的知识

    https://docs.oracle.com/en/database/oracle/oracle-database/index.html

    JiekeXu之路
  • 微服务RESTful接口文档生成神器Swagger初探

    在微服务构建的过程中,你也许发现写的那些restful风格的接口需要编写文档。 文档一般包括要输入哪些参数,哪些参数是必填的,哪些是选填的。还有返回结果的格式...

    ImportSource
  • Dynamsoft Camera SDK 6.0发布,轻松捕捉图像和视频流

    Dynamsoft Camera SDK提供了Java api,使您可以轻松地从浏览器兼容的USB视频类(UVC)网络摄像头捕捉图像和视频流。 ? 使用基于浏览...

    BestSDK
  • java安全编码指南之:文件和共享目录的安全性

    java程序是跨平台的,可以运行在windows也可以运行在linux。但是平台不同,平台中的文件权限也是不同的。windows大家经常使用,并且是可视化的权限...

    程序那些事
  • python轻量级中文搜索whoosh

    spark
  • 教程 | 一文读懂如何用LSA、PSLA、LDA和lda2vec进行主题建模

    在自然语言理解任务中,我们可以通过一系列的层次来提取含义——从单词、句子、段落,再到文档。在文档层面,理解文本最有效的方式之一就是分析其主题。在文档集合中学习、...

    IT派

扫码关注云+社区

领取腾讯云代金券