网站联系方式设计,网站免费建站app,免费发广告的平台有哪些,2022拉人头最暴利的app背景好像是上周四#xff0c;看到微信群有人说java有轮子swagger-bootstrap-ui#xff0c;而c##xff0c;就是找不到。于是我一看#xff0c;就说大话#xff1a;“这个只是一套UI#xff0c;他这个有开源地址么”被at说:你试试...当天晚上就把swagger-ui, Knife4j,Swas… 背景好像是上周四看到微信群有人说java有轮子swagger-bootstrap-ui而c#就是找不到。于是我一看就说大话“这个只是一套UI他这个有开源地址么”被at说:你试试...当天晚上就把swagger-ui, Knife4j,Swashbuckle.AspNetCore项目的源码都下载下来研究下看看能不能集成到AspNETCore下这样我们就能给Swagger UI换套新皮肤。knife4jknife4j 是swagger-bootstrap-ui库的升级版作者已全面升级全部以knife4j命名。Gitee上也有2.8K效果图IGeekFan.AspNetCore.Knife4jUI他是swagger ui 库knife4j UI 的.NET Core封装支持 .NET Core3.0或.NET Standard2.0。https://github.com/luoyunchong/IGeekFan.AspNetCore.Knife4jUI概念对应关系如下功能c#java实现swagger规范Swashbuckle.AspNetCorespring-fox封装成nuget包/maven包的UI库Swashbuckle.AspNetCore.SwaggerUIknife4j-v3-spring-uiUI库swagger-ui-distknife4j-vue-v3(swagger v3版本)注意swagger v2和v3版本不一样我只实现了swagger v3版本的封装。源码下载https://gitee.com/xiaoym/knife4jhttps://github.com/domaindrivendev/Swashbuckle.AspNetCoreSwashbuckle.AspNetCore.SwaggerUI源码分析。通过中间件SwaggerUI中间件MiddlewareInvoke方法中替换了Index.html中的%(DocumentTitle) %(HeadContent),%(ConfigObject)等等 。private readonly SwaggerUIOptions _options;
//xxxpublic async Task Invoke(HttpContext httpContext)
{
//xxxif (httpMethod GET Regex.IsMatch(path, $^/{Regex.Escape(_options.RoutePrefix)}/?index.html$)){await RespondWithIndexHtml(httpContext.Response);return;}
//xxx}private async Task RespondWithIndexHtml(HttpResponse response)
{response.StatusCode 200;response.ContentType text/html;charsetutf-8;using (var stream _options.IndexStream()){// Inject arguments before writing to responsevar htmlBuilder new StringBuilder(new StreamReader(stream).ReadToEnd());foreach (var entry in GetIndexArguments()){htmlBuilder.Replace(entry.Key, entry.Value);}await response.WriteAsync(htmlBuilder.ToString(), Encoding.UTF8);}
}private IDictionarystring, string GetIndexArguments()
{return new Dictionarystring, string(){{ %(DocumentTitle), _options.DocumentTitle },{ %(HeadContent), _options.HeadContent },{ %(ConfigObject), JsonSerializer.Serialize(_options.ConfigObject, _jsonSerializerOptions) },{ %(OAuthConfigObject), JsonSerializer.Serialize(_options.OAuthConfigObject, _jsonSerializerOptions) }};
}
在index.html中。title%(DocumentTitle)/title
var configObject JSON.parse(%(ConfigObject));
var oauthConfigObject JSON.parse(%(OAuthConfigObject));
当我们写的aspnetcore项目集成swagger组件后只会有一个ajax的异步请求knife4j-v3-spring-ui效果(2.X版)http://knife4j.xiaominfo.com/doc.html由于官方也没有v3的demo我们可以暂时通过v2分析,发现他有3个异步请求有一个请求返回相似的。另一个则是swagger的配置项可以发现返回值与SwaggerUIOptions一致。功能c# swagger v3javaswagger v2)获取分组配置无/swagger-resourcesswagger配置项无/swagger-resources/configuration/uiapi文档https://api.igeekfan.cn/swagger/v1/swagger.json/v2/api-docs?group2.X版本结构如下。版本分组配置http://knife4j.xiaominfo.com/swagger-resources[{name:2.X版本,url:/v2/api-docs?group2.X版本,swaggerVersion:2.0,location:/v2/api-docs?group2.X版本},{name:分组接口,url:/v2/api-docs?group分组接口,swaggerVersion:2.0,location:/v2/api-docs?group分组接口},{name:默认接口,url:/v2/api-docs?group默认接口,swaggerVersion:2.0,location:/v2/api-docs?group默认接口}
]
swagger 配置项http://knife4j.xiaominfo.com/swagger-resources/configuration/ui 请求方法: GET{deepLinking:true,displayOperationId:false,defaultModelsExpandDepth:1,defaultModelExpandDepth:1,defaultModelRendering:example,displayRequestDuration:false,docExpansion:none,filter:false,operationsSorter:alpha,showExtensions:false,tagsSorter:alpha,validatorUrl:,apisSorter:alpha,jsonEditor:false,showRequestHeaders:false,supportedSubmitMethods:[get,put,post,delete,options,head,patch,trace]
}
api 文档http://knife4j.xiaominfo.com/v2/api-docs?group2.X%E7%89%88%E6%9C%AC接下来我们看下knife4j,可以看到他有knife4j-vue-v3项目这个是swagger v3版本的vue实现。我们打开knife4j-vue-v3项目修改配置项vue.config.js,devServer 反向代理的地址(后台地址)proxy: {/: {target: http://localhost:5000/,ws: true,changeOrigin: true}
}
安装依赖并运行他yarn install
yarn serve
我们会看到一个请求错误。Knife4j文档请求异常因为后台并没有/v3/api-docs/swagger-config。也就是上文中的/swagger-resources/configuration/ui我们可以在SwaggerUIMiddleware中间件获取这些参数原本是通过替换字符串现在我们可以写一个api。怎么写呢。下载Swashbuckle.AspNetCore的源码打开Swashbuckle.AspNetCore.sln。我们尝试修改Swashbuckle.AspNetCore.SwaggerUI项目中,SwaggerUIMiddleware中的源码。Invoke方法增加如下处理将配置项直接返回json串。if (httpMethod GET Regex.IsMatch(path, $^/v3/api-docs/swagger-config$))
{await httpContext.Response.WriteAsync(JsonSerializer.Serialize(_options.ConfigObject, _jsonSerializerOptions));return;
}在swagger v3 版本中,/v3/api-docs/swagger-config,返回了分组信息,urls字段。效果如下image设置test/WebSites/Basic项目为启动项目运行后,打开了http://localhost:5000/index.html这个还是原本的swagger ui我们打开http://localhost:8080/#/home前台依旧提示有问题。AddSwaggerGen 需要增加Server前台判断有BUG非空。imageservers.length得到的是0问号表达式就会执行后面的servers[0].url临时方案services.AddSwaggerGen(c
{c.AddServer(new OpenApiServer(){Url ,Description v1});
});
但还有一个问题前台根据operationId生成的路由 [HttpPost(Name CreateProduct)]比如CreateProduct。有些没有设置 Name的点击后就会出现空白界面。增加CustomOperationIds的配置通过反射获取方法名。services.AddSwaggerGen(c
{//xxc.CustomOperationIds(apiDesc {return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;});
});
解决了这些问题。我们创建一个新类库起名IGeekFan.AspNetCore.Knife4jUI将前端打包。修改打包文件配置vue.config.jsassetsDir: knife4j,
indexPath: index.html
打包yarn run build
复制到根目录设置为嵌入文件删除不需要的images和txt文本。ItemGroupEmbeddedResource Includeknife4j/**/* /EmbeddedResource Includefavicon.ico /EmbeddedResource Includeindex.html /
/ItemGroup
将后台Swashbuckle.AspNetCore.SwaggerUI的代码复制过来全部重命名。比如中间件名字为SwaggerUIMiddleware - Knife4jUIMiddleware。即SwaggerUI都改成Knife4jUI。Knife4jUIMiddleware修改位置private const string EmbeddedFileNamespace IGeekFan.AspNetCore.Knife4jUI;
删除无用的替换变量增加Knife4UIOptions 修改public FuncStream IndexStream { get; set; } () typeof(Knife4UIOptions).GetTypeInfo().Assembly.GetManifestResourceStream(IGeekFan.AspNetCore.Knife4jUI.index.html);
Startup 中的Configure中间件将UseSwaggerUI()改成UseKnife4UI()app.UseKnife4UI(c
{c.RoutePrefix ; // serve the UI at rootc.SwaggerEndpoint(/v1/api-docs, V1 Docs);c.SwaggerEndpoint(/gp/api-docs, 登录模块);
});
不用IGeekFan.AspNetCore.Knife4jUI也能实现当然可以。我们也能通过其他方式在SwaggerUI的基础上替换比如替换Index.html页面自己打包前端UI复制到项目中等。将knife4j-vue-v3项目打包放到wwwwroot目录中。需要配置静态文件。 app.UseStaticFiles();
app.UseSwaggerUI(c
{c.RoutePrefix ; // serve the UI at rootc.SwaggerEndpoint(/v1/api-docs, V1 Docs);//这个配置无效。c.IndexStream () new PhysicalFileProvider(Path.Combine(Directory.GetCurrentDirectory(), wwwroot)).GetFileInfo(index.html).CreateReadStream();
});
重写/v3/api-docs/swagger-config路由app.UseEndpoints(endpoints
{endpoints.MapControllers();endpoints.MapSwagger({documentName}/api-docs);endpoints.MapGet(/v3/api-docs/swagger-config, async (httpContext) {JsonSerializerOptions _jsonSerializerOptions new JsonSerializerOptions();_jsonSerializerOptions.PropertyNamingPolicy JsonNamingPolicy.CamelCase;_jsonSerializerOptions.IgnoreNullValues true;_jsonSerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, false));SwaggerUIOptions _options new SwaggerUIOptions(){ConfigObject new ConfigObject(){Urls new ListUrlDescriptor{new UrlDescriptor(){Url/v1/api-docs,NameV1 Docs}}}};await httpContext.Response.WriteAsync(JsonSerializer.Serialize(_options.ConfigObject, _jsonSerializerOptions));});
});
IGeekFan.AspNetCore.Knife4jUI指南相关依赖项knife4jknife4j-vue-v3(不是vue3,而是swagger-ui-v3版本Swashbuckle.AspNetCoreSwashbuckle.AspNetCore.SwaggerSwashbuckle.AspNetCore.SwaggerGenDemoBasicKnife4jUIDemo???? 快速开始????安装包1.Install the standard Nuget package into your ASP.NET Core application.Package Manager : Install-Package IGeekFan.AspNetCore.Knife4jUI
CLI : dotnet add package IGeekFan.AspNetCore.Knife4jUI
2.In the ConfigureServices method of Startup.cs, register the Swagger generator, defining one or more Swagger documents.using System.Reflection;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using IGeekFan.AspNetCore.Knife4jUI;
???? ConfigureServices3.服务配置CustomOperationIds和AddServer是必须的。 services.AddSwaggerGen(c {c.SwaggerDoc(v1,new OpenApiInfo{Title API V1,Version v1});c.AddServer(new OpenApiServer(){Url ,Description vvv});c.CustomOperationIds(apiDesc {return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;});});
???? Configure中间件配置app.UseSwagger();app.UseKnife4UI(c
{c.RoutePrefix ; // serve the UI at rootc.SwaggerEndpoint(/v1/api-docs, V1 Docs);
});app.UseEndpoints(endpoints
{endpoints.MapControllers();endpoints.MapSwagger({documentName}/api-docs);
});
???? 效果图运行项目打开 https://localhost:5001/index.html#/homehttps://pic.downk.cc/item/5f2fa77b14195aa594ccbedc.jpg更多配置请参考https://github.com/domaindrivendev/Swashbuckle.AspNetCore更多项目https://api.igeekfan.cn/swagger/index.htmlhttps://github.com/luoyunchong/lin-cms-dotnetcore
