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 文档, 要舒服, 省事儿得多?
来源: https://www.cnblogs.com/guokun/p/12555556.html