- VisualStudio2022插件的安装及使用-编程手把手系列文章
- pprof-在现网场景怎么用
- C#实现的下拉多选框,下拉多选树,多级节点
- 【学习笔记】基础数据结构:猫树
公司项目是是微服务项目,网关是手撸的一个.net core webapi 项目,使用 refit 封装了 20+ 服务 SDK,在网关中进行统一调用和聚合等处理,以及给前端提供 swagger 文档 在我两年前进公司的时候,文档还能够顺滑的打开,在去年的时候文档只能在本地打开,或者访问原始的 swagger 页面,knife4j 的页面更是打不开一点,于是想办法对此进行了优化 。
首先再记录一下安装及使用,之前也分享过 Swashbuckle.AspNetCore 的使用,不过版本比较老了,本次演示用的示例版本为 .net core 8.0,从安装使用开始分享一二 。
<ItemGroup>
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
<PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.6.2" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.6.2" />
</ItemGroup>
<PropertyGroup>
<DocumentationFile>bin\$(MSBuildProjectName).xml</DocumentationFile>
</PropertyGroup>
c.SwaggerDoc
c.AddServer
c.CustomSchemaIds
c.CustomOperationIds
c.IncludeXmlComments
c.EnableAnnotations [SwaggerOperation]
//框架初始化巴拉巴拉xxx
builder.Services.AddControllers();
//配置 swagger
UseSwagger(builder.Services);
/// <summary>
/// Swagger 注入配置
/// </summary>
/// <param name="services"></param>
/// <returns></returns>
void UseSwagger(IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
//配置文档信息
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "swagger接口文档测试",
Description = "这是一个文档",
Version = "v1",
});
//配置环境
c.AddServer(new OpenApiServer()
{
Url = "",
Description = "本地"
});
//配置模型标识,默认type.Name,名称一样,不同明明空间会报错,所以改成FullName,加上命名空间区分
c.CustomSchemaIds(type => type.FullName);
//配置唯一标识
c.CustomOperationIds(apiDesc =>
{
var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
return controllerAction.ControllerName + "-" + controllerAction.ActionName;
});
//解析站点下所有xml,一般加自己项目的引用的即可
foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
{
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, file));
}
//启用数据注解
c.EnableAnnotations(true, true);
});
}
RunSwagger(app);
/// <summary>
/// 启用swagger
/// </summary>
/// <param name="app"></param>
void RunSwagger(IApplicationBuilder app)
{
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
});
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapSwagger("{documentName}/api-docs");
endpoints.MapGet("/v3/api-docs/swagger-config", async (httpContext) =>
{
JsonSerializerOptions jsonSerializerOptions = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
IgnoreNullValues = true
};
jsonSerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, false));
SwaggerUIOptions _options = new SwaggerUIOptions()
{
ConfigObject = new ConfigObject()
{
Urls = new List<UrlDescriptor>
{
new UrlDescriptor()
{
Url="/v1/api-docs",
Name="V1 Docs"
}
}
}
};
await httpContext.Response.WriteAsync(JsonSerializer.Serialize(_options.ConfigObject, jsonSerializerOptions));
});
});
}
到这里基础的 swagger 配置已可以使用,更深层次的参考官方文档使用即可,接下来才是不一样的东西 随着我们的项目发展,当我们的服务越来越多,接口也越来越多的时候,swagger 就从慢,到打开超时偶尔能打开,到每次都打不开(/api-docs 过大返回超时,渲染卡顿) 这个时候,或者一开始就应该对 swagger 进行分组返回了,优化 /api-docs 接口返回的数据 当然,除了这种方式,还有可以加特效标记的方式,但是几百个服务,加不了一点 。
一开始并没有想到分组显示,因为在本地运行的时候是可以打开的,只是 json 文件较大,于是做了一个优化是每次在发布应用后,请求一个接口去将 swagger 的 json 文件生成到本地,后续访问直接读取,算是暂时解决了打不开的问题,这样用了大半年,实在受不了这个速度,然后平时在看一些开源项目的时候发现是完全可以按自己的规则进行分组的,于是有了这篇文章 。
为了兼容之前的文档路由,所以还是在原有配置的基础上,配置了其他模块的接口文档 可有两种方式 。
//设置需要分组的api接口
var groupApis = new List<string>() { "SwaggerTest.Controllers.Test", "SwaggerTest.Controllers.Demo" };
//配置文档信息
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "swagger接口文档测试",
Description = "这是一个文档",
Version = "v1",
});
//配置环境
c.AddServer(new OpenApiServer()
{
Url = "",
Description = "本地"
});
//模型标识配置,默认type.Name,名称一样,不同明明空间会报错,所以改成FullName,加上命名空间区分
c.CustomSchemaIds(type => type.FullName);
c.CustomOperationIds(apiDesc =>
{
var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
return controllerAction.ControllerName + "-" + controllerAction.ActionName;
});
//加载注释文件
foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
{
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, file));
}
//增加模块接口的注册
groupApis.ForEach(s =>
{
c.SwaggerDoc(s, new OpenApiInfo
{
Title = "api-" + s,
Description = "api " + s,
Version = "v1",
});
});
//启用数据注解
c.EnableAnnotations(true, true);
//自定义分组匹配
c.DocInclusionPredicate((docName, apiDes) =>
{
if (groupApis.Contains(docName))
{
var displayName = apiDes.ActionDescriptor?.DisplayName?.ToLower() ?? string.Empty;
var existGroup = groupApis.FirstOrDefault(s => displayName.Contains(s.ToLower()));
return docName == existGroup;
}
return true;
});
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
//默认页支持分组
groupApis.ForEach(s =>
{
c.SwaggerEndpoint($"/{s}/api-docs", s);
});
});
//单独的页面
groupApis.ForEach(s =>
{
app.UseSwaggerUI(c =>
{
c.RoutePrefix = s;
c.SwaggerEndpoint($"/{s}/api-docs", s);
});
});
app.UseEndpoints(endpoints =>
{
SwaggerUIOptions _options = new SwaggerUIOptions()
{
ConfigObject = new ConfigObject()
{
Urls = new List<UrlDescriptor>
{
new UrlDescriptor()
{
Url="/v1/api-docs",
Name="V1 Docs"
}
}.Concat(groupApis.Select(s => new UrlDescriptor()
{
Url = $"/{s}/api-docs",
Name = s
}).ToList())
}
};
})
修改完成后,可以结合自己业务来定义需要单独显示分组,最近又基于此加了一个开放平台的接口,独立于正常网关,单独提供出去,一切都是刚刚好~ 。
如果有更好的方式,欢迎分享 若有错误,欢迎指出,谢谢 。
最后此篇关于基于.netcore8.0的swagger文档优化分享-根据命名空间分组显示的文章就讲到这里了,如果你想了解更多关于基于.netcore8.0的swagger文档优化分享-根据命名空间分组显示的内容请搜索CFSDN的文章或继续浏览相关文章,希望大家以后支持我的博客! 。
我试图在我的微服务项目中生成一个单一的 swagger,在 Api 网关中将所有服务 swagger 聚合成一个单一的服务。为了实现这一点,我正在学习下一个教程 https://objectpartn
我的任务是将 Swagger 安装到 Web API 项目中。 已安装:来自 nuget 的最新版本的 Swashbuckle。 (Swashbuckle.Core.Net45 和 Swashbuck
我正在编写一个 swagger 规范,并且我有三个独立的端点。我如何在文档中将它们分开?我想明确区分示例:用户、帖子和其他。所以每个人都会有一个 CRUD 描述并显示在 swagger UI 中,它看
我试图在 Swagger 中定义一个查询参数,其中包含来自预定义项目集的逗号分隔字符串,例如 ?fruits=Apples,Oranges,Bananas但我从 swagger 编辑器收到以下错误 s
我正在使用 go-swagger 来生成 API 服务器。我注意到从 swagger.yml 生成的 json 被保存在 restapi/embedded_spec.go 中. 公开该 JSON 规范
我使用的是 springfox 版本 2.9.2 和 swagger 注释 1.5.x。 ApiModel 注释支持鉴别器、子类型和父属性,这些是使多态性工作所需的,但我没有看到生成的正确的 apid
我正在尝试使用本地 swagger.json 文件在 swagger 文档中显示。 我的 swagger.json 文件位于/home/user1/swagger-ui/dist/swagger.js
我们有一些数字字段,由于遗留原因,它们具有隐式长度限制。 给定一个长度限制为 5 的数字字段,显而易见的方法是将最大值设置为 99999,但是有没有办法在 swagger 规范中指定 1.111 可以
我们的项目为单个 API 使用多个 swagger 文件,但看起来 swagger-codegen 只接受一个。在这种情况下,我们如何使用 swagger-codegen 生成代码? 最佳答案 您可以
我正在尝试使用 https://github.com/swagger-api/swagger-codegen 生成 nodejs 客户端 sdk这是我使用的命令 swagger-codegen gen
我定义了一个以 MyObject 作为参数的路径。 MyObject 具有猫和狗的属性。这些有默认值。 在 swagger-editor 中,该示例不显示默认值,但试用确实创建了一个具有正确默认值的
我最近从 Swashbuckle 过渡到 Swagger-Net .进行更改后我遇到的一个问题是,现在我无法调用需要在 Authorization header 中发送 token 的 API。下面是
正在使用 AspNetCore 为使用 IIS 托管的 Web 应用程序设置 swagger。 .json 页面加载并且似乎可以很好地接触所有 API,但是当导航到 {localhost}/swagg
我想将任何复杂的 swagger-API-document(swagger.json) 解析为 Java 对象。 可能是列表> 有哪些可用选项? 我正在尝试使用 io.swagger.parser.S
我要将我的 API 服务器集成到 Google Cloud Endpoints。 到目前为止,Google Cloud Endpoints 支持 swagger 2.0。 但是我的依赖项/库现在是 u
我是 swagger 的新手,发现有两个用于 swagger 注释的包:io.swagger.annotations 和 com.wordnik.swagger.annotations。我想知道它们之
好的,我有许多 io.swagger.models.Swagger 对象,我已将它们合并到一个新的 super Swagger 中。现在我想要 super html。我怎样才能得到这个?请注意,为了获
我们当前的部署模式要求我手动编写 swagger json 输出,该输出将由我公司使用的基于 Swagger 的 UI 使用。我希望我正在编写的 json 能够提供“默认”值来填充所有输入字段(包括
我有以下 HTTP 触发的 Azure 函数。我已经使用此链接为我的端点设置了 Swagger here .以下 API 需要一组查询字符串参数,即 "name"、"email"、"phone",因此
我正在努力让 Swagger 正确呈现我的 ServiceStack 服务。 我希望看到一个 UserId 字符串作为表单参数,一个 PrivateCustomer 对象作为主体参数,但是尽管 Use
我是一名优秀的程序员,十分优秀!