亚洲城体育备用代理亚洲城体育备用代理


亚洲城集团备用代理

Swagger 导出API

Swagger 导出API

这算是在博客园的第一篇博客吧,之后发的应该也会同步到博客园上。

此前的博客地址: https://gitbook.mytyiluo.cn

Swagger简介

Swagger是一个开源软件框架,可帮助开发人员设计,构建,记录和使用RESTful Web服务。

其中,Swagger可以生成一个交互式的API控制台,以便于快速测试API。

从个人角度讲,Swagger对于前后端分离的小团队来说是非常有帮助的。尤其是像我们这种平时没写文档习惯的人来说,Swagger能根据代码自动生成文档可谓是一大福音,再也不用被人追着问这API到底是怎么用的。

这里,我将会具体说下最近我使用Swagger的一些心得和体会,团队的开发环境如下:

ASP.NET Core 2.1 (Visual Studio 2017 Community)微信小程序 (官方工具+Visual Studio Code)

生成Swagger API 文档

对于ASP.NET Core来说,生成文档这一步还是相对容易的,且对代码基本没有侵入性。只需在Startup中配置一下即可,大致步骤基本如下:

添加NuGet包

这里,我所使用的是Swashbuckle.AspNetCore,直接用VS的NuGet包管理器下载即可。

然后在ConfigureServices中配置如下:

services.AddSwaggerGen(c =>{ // 定义文档 c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" });});

并在Configure中启用该Services:

// 使用Swaggerapp.UseSwagger();app.UseSwaggerUI(c =>{ c.SwaggerEndpoint("/swagger/v1/swagger.json", "Qincai API v1");});

随后运行,打开浏览器host/swagger即可看到所生成的API文档。

若还有不清楚的,可以参考微软官方的文档。

完成到这里,是不是发现你和图中生成的样子有点不太一样,比如说,为什么没有注释,以及认证用的小锁,那这里我们就需要进一步配置。

添加XML注释

如果大家有在VS中写C#经历的话,肯定会对XML注释影响深刻,通过简单的///就可以自动生成规范的注释格式。那这里,我们的Swagger也正是利用了这些XML注释来标记对应的API。

首先,我们需要启用VS中导出XML文档的功能,在项目属性中,生成 > 输出,勾选XML文档文件,并填写对应的路径,我所写的是项目根目录。

然后再到之前的ConfigureServices中添加如下:

services.AddSwaggerGen(c =>{ c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" }); // file 是你在项目属性中配置的相对路径 var filePath = System.IO.Path.Combine(AppContext.BaseDirectory, file); c.IncludeXmlComments(filePath);});

重新生成,再运行,你可以看到Swagger中就对API以及参数添加上了注释。

添加认证功能

在实际开发中,我们常常是需要给我们的API添加上认证功能以避免非法的访问,因此我们也就需要给Swagger中的API标识上是否需要认证,并且添加提供Token的功能,以方便在Swagger的控制台中调试。

简单来说,还是在ConfigureServies中,配置如下:

services.AddSwaggerGen(c =>{ c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" }); var filePath = System.IO.Path.Combine(AppContext.BaseDirectory, file); c.IncludeXmlComments(filePath); // 定义认证方式 c.AddSecurityDefinition("Bearer", new ApiKeyScheme { In = "header", Description = "请键入JWT Token,格式为"Bearer "+你的Token。", Name = "Authorization", Type = "apiKey" }); // 网上为全局API添加认证参数的方法 // c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> { // { "Bearer", Enumerable.Empty<string>() }, // }); // 在过滤器中为需要认证的API添加对应参数 // 过滤器的定义见下文 c.OperationFilter<AuthorizationHeaderOperationFilter>();});

这里值得说一下的是,网上普遍都是全局添加认证参数,导致一些不需要认证的API也被打上了标识,这在Swagger 控制台中影响倒不大,但在后续的导出API时就麻烦了,所有在这里,我使用自定义过滤器的方式来只为需要认证的API添加认证参数。

根据上文,我们先定义一个AuthorizationHeaderOperationFilter类,它需要实现IOperationFilter接口,类定义如下:

/// <summary>/// 判断是否需要添加Authorize Header/// </summary>public class AuthorizationHeaderOperationFilter : IOperationFilter{ /// <summary> /// 为需要认证的Operation添加认证参数 /// </summary> /// <param name="operation">The Swashbuckle operation.</param> /// <param name="context">The Swashbuckle operation filter context.</param> public void Apply(Operation operation, OperationFilterContext context) { // 获取对应方法的过滤器描述 // 应该也就是所添加的Attribute var filterPipeline = context.ApiDescription.ActionDescriptor.FilterDescriptors; // 判断是否添加了AuthorizeFilter // 也就是[Authorize] var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is AuthorizeFilter); // 判断是否添加了IAllowAnonymousFilter // 也就是[AllowAnonymous] var allowAnonymous = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is IAllowAnonymousFilter); // 仅当需要认证且不是AllowAnonymous的情况下,添加认证参数 if (isAuthorized && !allowAnonymous) { // 若该Operation不存在认证参数的话, // 这个Security将是null,而不是空的List if (operation.Security == null) operation.Security = new List<IDictionary<string, IEnumerable<string>>>(); // 添加认证参数 operation.Security.Add(new Dictionary<string, IEnumerable<string>> { { "Bearer", new string[] { } } }); } }}

重新生成后运行,应该就可以看到需要认证的API都带上了一把小锁。

注意事项

虽说配置并不算难,但还是需要注意一些地方。

    注意写好XML注释

    之前也说了,Swagger的注释是根据XML文档生成的,反过来说,如果你没写XML注释,Swagger上也就是不会有注释的。

    另外,在你启用XML文档输出之后,VS也会很贴心的为你把没有写XML注释的地方都标为Warning。╮(╯▽╰)╭,所以安心的把注释都补一遍吧。

    为参数添加数据注解

    Swagger是支持部分数据注解的,比如[Required]之类的。

    结合[ApiController]自带的模型验证功能,岂不美哉。

    将XML文档复制到输出目录

    若你在发布应用后发现XML不见了,那可能就是你没有为XML文档文件配置复制到输出目录的属性。

    打开资源管理器,右键对应的文件,我们在属性中可以看到有复制到输出目录的属性,将其设置为始终复制就Ok。

以上就是我最近所用到的Swagger的一些功能。

导出微信小程序可用的API

在一开始也说了,使用Swagger的主要目的就是方便小团队的沟通,但事实上,因为我们前端的人少(大家都是CSS鬼才),导致我们开发新API的速度往往比前端进度快,没几天前端那边就需要更新一下API的库(将小程序的CallBack封装成Promise)。

因此,就有了根据Swagger自动生成Js可用的API文件的想法,其实想法的本身是来自于Abp项目的设计(真的很优秀),但出于一些方面的考虑,我们姑且还没采用Abp。

随后,就是查找资料了,确实Swagger有这方面的支持,其中官方关于Js的库是完全动态的,但可惜不适用于小程序。然后,就发现了第三方的swagger-js-codegen,可用于生成静态的Js代码,且提供了自定义模板的功能。网上也不少基于这个库的其他模板,比如说axios之类的,但没有适用于微信小程序的,不过问题不大,模板是基于mustache的,动手撸就是了。

模板代码有点长就不在这里放出了,大家还请移步GitHub。

这里我就简单说下大致思路,

模板本身是基于原来的nodejs模板改的,我们所需做的就是将http请求部分的代码改为使用wx.request,如下简单的封装即可:

/*** HTTP Request* @method* @name {{&className}}#request* @param {string} method - HTTP 请求方法* @param {string} url - 开发者服务器接口地址* @param {object} data - 请求的参数* @param {object} headers - 设置请求的 header ,默认为 application/json*/request(method, url, parameters, data, headers){ return new Promise((resolve, reject) => { wx.request({ url: url, data: data, header: headers, method: method, success: res => { if(res.statusCode >= 200 && res.statusCode <= 299) { resolve(res.data) } else { reject(res) } }, fail: e => reject(e) }) })}

对应method的话,基本没怎么改,只根据微信小程序所有参数都是传递给data,做了点简化。

对于认证部分,根据我们自己的需求,换成了这样的实现:

new Promise((resolve, reject) => { this.authenticate() .then(token => { headers["Authorization"] = "Bearer " + token; resolve(this.request("{{method}}", domain + path, parameters, data, headers)) })})

其中this.authenticate是由外部传入的function,返回一个包含TokenPromise

导出后,在小程序中的使用就类似于:

import API from "./api.js"api = new API("http://localhost:5000")api.setAuthenticate(function () { return new Promise((resolve, reject) => { // 你的认证逻辑 resolve(token) })})

然后,就可以开心地调用各种方法了。

最后,再放一遍Demo的链接:https://github.com/yiluomyt/swagger-wxopen-codegen-template,发现有问题欢迎提Issue。

, 1, 0, 9);

欢迎阅读本文章: 易静

亚洲城集团官方APP

亚洲城集团备用代理