示例请求正文中 JsonPatchDocument 的 Swagger 意外 API PATCH 操作文档 [英] Swagger unexpected API PATCH action documentation of JsonPatchDocument in example request body
问题描述
我正在制作 Core 3.1 Web API 并使用
我不熟悉这种结构,甚至其中缺少 value"
属性,这是 JsonPatchDocument
对象所具有的.我见过的每个使用 replace
操作打补丁的例子都有第一个结构.
为什么 Swagger 为 PATCH 端点的请求正文中的 JsonPatchDocument
对象生成替代结构?我该如何解决这个问题?
为 Swagger 安装的 NuGet 包:
Swashbuckle.AspNetCore
不适用于此类型 JsonPatchDocument
t 表示预期的补丁请求文件.
您需要自定义文档过滤器来修改生成的规范.
公共类 JsonPatchDocumentFilter : IDocumentFilter{公共无效应用(OpenApiDocument swaggerDoc,DocumentFilterContext 上下文){var schemas = swaggerDoc.Components.Schemas.ToList();foreach(架构中的 var 项目){if (item.Key.StartsWith(Operation") || item.Key.StartsWith(JsonPatchDocument"))swaggerDoc.Components.Schemas.Remove(item.Key);}swaggerDoc.Components.Schemas.Add("Operation", new OpenApiSchema{类型 = 对象",Properties = new Dictionary{{op",新的 OpenApiSchema{ Type = string";} },{value", new OpenApiSchema{ Type = string"} },{path", new OpenApiSchema{ Type = string";} }}});swaggerDoc.Components.Schemas.Add("JsonPatchDocument", new OpenApiSchema{类型 = 数组",项目 = 新的 OpenApiSchema{Reference = new OpenApiReference { Type = ReferenceType.Schema, Id = "Operation";}},Description =要执行的操作数组";});foreach(swaggerDoc.Paths.SelectMany(p => p.Value.Operations)中的var路径.Where(p => p.Key == Microsoft.OpenApi.Models.OperationType.Patch)){foreach (var item in path.Value.RequestBody.Content.Where(c => c.Key != "application/json-patch+json"))path.Value.RequestBody.Content.Remove(item.Key);var response = path.Value.RequestBody.Content.Single(c => c.Key == "application/json-patch+json");response.Value.Schema = 新的 OpenApiSchema{Reference = new OpenApiReference { Type = ReferenceType.Schema, Id = "JsonPatchDocument";}};}}}
注册过滤器:
services.AddSwaggerGen(c => c.DocumentFilter());
结果:
I'm making a Core 3.1 web API and using JsonPatch to create a PATCH action. I have an action named Patch
which has a JsonPatchDocument
parameter. Here is the action's signature:
[HttpPatch("{id}")]
public ActionResult<FileRecordDto> Patch(int id, [FromBody] JsonPatchDocument<FileRecordQueryParams> patchDoc)
As I understand, the parameter needs to receive JSON data in the following structure, which I've successfully tested with the action:
[
{
"op": "operationName",
"path": "/propertyName",
"value": "newPropertyValue"
}
]
However, the action's documentation generated by Swagger has a different structure:
I'm not familiar with this structure and even "value"
property is missing from it, which a JsonPatchDocument
object has. Every example of patching with the replace
operation I've seen has had the first structure.
Why is Swagger generating an alternate structure for a JsonPatchDocument
object in the request body for the PATCH endpoint? How do I fix this?
The NuGet package installed for Swagger:
Swashbuckle.AspNetCore
doesn't work propertly with this type JsonPatchDocument<UpdateModel>
, which doesn’t represent the expected patch request doument.
You need to custome a document filter to modify the generated specification.
public class JsonPatchDocumentFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
var schemas = swaggerDoc.Components.Schemas.ToList();
foreach (var item in schemas)
{
if (item.Key.StartsWith("Operation") || item.Key.StartsWith("JsonPatchDocument"))
swaggerDoc.Components.Schemas.Remove(item.Key);
}
swaggerDoc.Components.Schemas.Add("Operation", new OpenApiSchema
{
Type = "object",
Properties = new Dictionary<string, OpenApiSchema>
{
{"op", new OpenApiSchema{ Type = "string" } },
{"value", new OpenApiSchema{ Type = "string"} },
{"path", new OpenApiSchema{ Type = "string" } }
}
});
swaggerDoc.Components.Schemas.Add("JsonPatchDocument", new OpenApiSchema
{
Type = "array",
Items = new OpenApiSchema
{
Reference = new OpenApiReference { Type = ReferenceType.Schema, Id = "Operation" }
},
Description = "Array of operations to perform"
});
foreach (var path in swaggerDoc.Paths.SelectMany(p => p.Value.Operations)
.Where(p => p.Key == Microsoft.OpenApi.Models.OperationType.Patch))
{
foreach (var item in path.Value.RequestBody.Content.Where(c => c.Key != "application/json-patch+json"))
path.Value.RequestBody.Content.Remove(item.Key);
var response = path.Value.RequestBody.Content.Single(c => c.Key == "application/json-patch+json");
response.Value.Schema = new OpenApiSchema
{
Reference = new OpenApiReference { Type = ReferenceType.Schema, Id = "JsonPatchDocument" }
};
}
}
}
Register the filter:
services.AddSwaggerGen(c => c.DocumentFilter<JsonPatchDocumentFilter>());
Result:
这篇关于示例请求正文中 JsonPatchDocument 的 Swagger 意外 API PATCH 操作文档的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!