- Java锁的逻辑(结合对象头和ObjectMonitor)
- 还在用饼状图?来瞧瞧这些炫酷的百分比可视化新图形(附代码实现)⛵
- 自动注册实体类到EntityFrameworkCore上下文,并适配ABP及ABPVNext
- 基于Sklearn机器学习代码实战
非常喜欢. NET 的 /// 注释,写代码的时候就顺道完成写文档的过程,简直不要太爽了。 ASP. NET CORE 也是一样的,通过 Swagger 工具,可以自动生成 API 的接口文档(OpenAPI 规范 ),提供给前端使用,也可以用过 APIPOST/APIFOX 之类的工具提供给前端同学直接调用.
只需要安装 swashbuckle.aspnetcore 包,在项目上设置生成 XML 格式的注释,并且如下配置即可自动生成 OpenAPI 的文档,对我这个例子,可以通过 swagger/v{version}/swagger.json 访问.
services.AddSwaggerGen(options =>
{
// options.CustomSchemaIds(type => type.AssemblyQualifiedName);
var fileName = Assembly.GetExecutingAssembly().GetName().Name + ".xml";
var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
// integrate xml comments
options.IncludeXmlComments(filePath);
});
app.UseSwagger();
app.UseSwaggerUI(
options =>
{
foreach (var description in app.DescribeApiVersions())
{
var url = $"/swagger/{description.GroupName}/swagger.json";
var name = description.GroupName.ToUpperInvariant();
options.SwaggerEndpoint(url, name);
}
});
注释如下:
/// <summary>
/// 这个接口
/// </summary>
public class CoverageDataController : ODataController
{
/// <summary>
/// 获取盖度数据
/// </summary>
/// <param name="key"></param>
/// <param name="options"></param>
/// <returns></returns>
[HttpGet]
[ProducesResponseType(typeof(CoverageDataDto), Status200OK)]
public async Task<IActionResult> Get(string key, ODataQueryOptions<CoverageDataDto> options)
{
}
}
在使用 APIFOX 导入 swagger.json 导入时,我发现,对每一个 path 的注释能够正常显示,但是对的控制器的注释不能正常被识别.
查看生成的 swagger.json ,这个 CoverageData 被解释成了 OpenAPI 的 Tags,那对应控制器的相关注释,是需要使用另外的标注实现的,而不能直接使用///的注释实现.
paths": {
"/api/v{version}/CoverageData({key})": {
"get": {
"tags": [
"CoverageData"
],
"summary": "获取盖度数据",
安装的新的包 swashbuckle.aspnetcore.annotations ,然后增加启用语句,如下:
services.AddSwaggerGen(options =>
{
// options.CustomSchemaIds(type => type.AssemblyQualifiedName);
var fileName = Assembly.GetExecutingAssembly().GetName().Name + ".xml";
var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
// integrate xml comments
options.IncludeXmlComments(filePath);
options.EnableAnnotations();
});
在控制器的声明上面,添加 [SwaggerTag("接受盖度数据")] 注解:
/// <summary>
/// 这个接口
/// </summary>
[SwaggerTag("接受盖度数据")]
public class CoverageDataController : ODataController
{
}
最后生成的 swagger.json 文件在末尾多了几行:
"tags": [
{
"name": "CoverageData",
"description": "接受盖度数据"
}
]
Swagger 里面就可以看到注释了:
但是导入到 APIFOX 中,显示的组别名称依然是 CoverageData ,没有达到我想要的效果,我想将其替换成可以显示友好的名称。实质上是为 CoverageData 取一个别名.
注:这种方法不能与 swagger 配置的 TagActionsBy 方法的一起使用.
在 ASP. NET CORE 中,可以在控制器上使用 [Tags("盖度接口")] ,对控制器的组别进行标注。这样生成的 tag 名称直接就换成了的中文名称.
"paths": {
"/api/v{version}/CoverageData({key})": {
"get": {
"tags": [
"盖度接口"
],
"summary": "获取盖度数据",
....
"tags": [
{
"name": "CoverageData",
"description": "接受盖度数据"
}
]
但是 swagger 变得非常奇怪:
出现了两个不同的 tag,其中 CoverageData 名称的下面没有从属的 api.
如果没有对 Tag 写 description 的要求,那么使用这个方案是最简单的:设置[Tags],不要设置[SwaggerTag].
这么看应该是通过 swagger 生成的 tag 与通过 [Tags] 注解生成的 tag 对象不能匹配,导致 swagger 生成的没用被引用.
查了很久资料,说这个是一个现在的 Bug ,有人通过重写 DisplayName,在帖子中给了临时的 解决方案 :
/// <summary>
/// Uses the [DisplayName] attribute as the Controller name in OpenAPI spec and Swagger/ReDoc UI if available else the default Controller name.
/// </summary>
public class ControllerDocumentationConvention : IControllerModelConvention
{
void IControllerModelConvention.Apply(ControllerModel controller)
{
if (controller == null)
{
return;
}
foreach (var attribute in controller.Attributes)
{
if (attribute is DisplayNameAttribute displayNameAttribute && !string.IsNullOrWhiteSpace(displayNameAttribute.DisplayName))
{
controller.ControllerName = displayNameAttribute.DisplayName;
}
}
}
}
services.AddControllers(o =>
{
o.Conventions.Add(new ControllerDocumentationConvention());
});
[DisplayName("targetNames")]
即可。可以看到名称与注释都得到的保留,最终效果如下:
导入 APIFOX 也可以正常识别了.
最后此篇关于为控制器生成OpenAPI注释的文章就讲到这里了,如果你想了解更多关于为控制器生成OpenAPI注释的内容请搜索CFSDN的文章或继续浏览相关文章,希望大家以后支持我的博客! 。
所以`MKAnnotation's。有趣的东西。 我的问题: 注释的标题和副标题有什么区别?这对注释的视觉组件有何影响? MKPinAnnotationView 和 MKAnnotationView
我正在使用 JBoss 工具将 DB 模式反向工程到 POJO 中。具体来说,我在 hibernatetool ANT 任务中使用了 hbm2java 选项。在 hbm2java 选项下,您可以指定
假设我有这段文字: cat file /* comment */ not a comment /* another comment */ /* delete this * /* multiline
我明白,如果你///在类、字段、方法或属性上方 Visual Studio 将开始为您建立 XML 样式的注释。 但是,我在哪里可以为我的命名空间和/或库添加 XML 注释... 例如: .NET F
int API_VERSION = 21; @TargetApi(API_VERSION)在Android中用于指定该方法/类支持API_VERSION及以下。 我们是否可以镜像类似的东西,指定仅支持
Closed. This question needs to be more focused。它当前不接受答案。
假设我有一个界面如下。 public interface MyInterface{ /** * This method prints hello */ void sayHello();
我已将 Jboss 应用程序迁移到 WebSphere Liberty。我必须删除所有 Jboss 引用库。在这样做的同时,我在某些注释中面临问题。 Jboss 应用程序使用 @SecurityDom
在本教程中,您将了解 JavaScript 注释,为什么要使用它们以及在示例的帮助下如何使用它们。 JavaScript 注释是程序员可以添加的提示,以使代码更易于阅读和理解。JavaScri
我正在建立一个博客,为了发表评论,我有这个 CSS。 #comments { position:absolute; border: 1px solid #900; border-width: 1
我正在尝试在单元格中插入评论。我正在尝试按照代码进行评论,但它没有在创建的 excel 中显示评论。我正在创建 .xls 扩展名。 $objPHPExcel->getActiveSheet()->ge
我正在使用 TS 在 MarionetteJS 上编写项目,我想使用注释来注册路由。例如: @Controller class SomeController { @RouteMapping("so
我有一个应用程序可以在页面上生成大量注释。用户可以单击页面上的任意位置以创建快速注释(例如 Acrobat Pro)可以在一般 中使用一些 javascript 行添加和删除这些注释
是否有 JavaScript 注释? 当然 JavaScript 没有它们,但是是否有额外的库或建议的语言扩展,例如 @type {folder.otherjsmodule.foo} function
Java 中注解的目的是什么?我有一个模糊的想法,认为它们介于注释和实际代码之间。它们在运行时会影响程序吗? 它们的典型用法是什么? 它们是 Java 独有的吗?有 C++ 等价物吗? 最佳答案 注解
其实我们在 Ruby 基础语法 已经比较详细的介绍了 Ruby 语言中的注释 Ruby 解释器会忽略注释语句 注释会对 Ruby 解释器隐藏一行,或者一行的一部分,或者若干行。 Ruby 中的注
我正在 try catch VBA 注释。到目前为止,我有以下内容 '[^";]+\Z 它捕获以单引号开头但在字符串结尾之前不包含任何双引号的任何内容。即它不会匹配双引号字符串中的单引号。 dim s
有没有办法在'svn commit'上将提交注释添加到更改的文件中。有人告诉我有一种方法可以用 cvs 做到这一点,但我们使用 svn。目前,我们使用“$Revision”关键字将修订号添加到更改的文
我正在尝试通过 ManyToMany 注释自动对报告的结果进行排序 @OrderBy : /** * @ORM\ManyToMany(targetEntity="Artist", inversedB
我正在使用 JBoss 5 GA,我创建了一个测试 session bean 和本地接口(interface)。我创建了一个 servlet 客户端。我尝试使用 @EJB 将接口(interface)
我是一名优秀的程序员,十分优秀!