ServiceStack - 使用 OpenApiFeature 自定义生成的 OpenAPI JSON

Question

使用 ServiceStack OpenApiFeature，openapi.json 文件中生成的 operationId 遵循以下约定:

[RequestName][没有第一个路径的路由路径切片*][http 动词][数字(如果需要唯一性)

没有第一个路径的路由路径切片*只是删除路径中的第一项。因此，如果路由路径是 blog/author/name，逻辑将获取 author/name。

这是在 OpenApiService::GetOperationName method 中定义的。在某些情况下，此逻辑会在依赖 openapi.json 的工具中创建次优操作命名。例如，如果您有一项服务公开客户详细信息、客户摘要等的 GET 操作，并且详细信息请求的定义如下:

[Api("Get a customer's details.")]
[Route("/customer/details", "GET")]
public class GetCustomerDetailsRequest : IReturn<GetCustomerDetailsResponse>
{ ... }

路线将是这样的(这很好): /customer/details?customerId=2

...但是生成的 OpenAPI operationId 将为 GetCustomerDetailsRequestdetails_Get，这不太好。

有没有办法使用OpenApiFeature自定义生成的operationId？如果没有，是否有其他命名约定可以维护 REST 式的路由约定，但提供更好的 OpenAPI operationId？

编辑:感谢mythz用于指出 ApiDeclarationFilter。它允许您完成自定义生成的openapi.json。这就是我更改 operationId 的方式:

Plugins.Add(new OpenApiFeature
        {
            ApiDeclarationFilter = declaration =>
            {
                foreach (var p in declaration.Paths)
                {
                    foreach (var httpVerb in _httpVerbs) // _httpVerbs is just a list of http verbs
                    {
                        // retrieve the operation value using reflection and pattern matching.  This is to prevent having to use a switch statement to go through each http verb and check if it's been implemented
                        if (p.Value.GetType().GetProperty(httpVerb).GetValue(p.Value) is OpenApiOperation operation)
                        {
                            // Set the "OperationId" property using the convention [RequestClassName]_[Http Verb].  Note for simplicity here, I'm not checking for a unique operation Id.  You should do that to ensure open api compliance
                            ReflectionHelper.SetProperty($"{httpVerb}.OperationId", p.Value,
                                $"{operation.RequestType}_{httpVerb}");
                        }
                    }
                }
            }
        });

Answer 1

除了 API metadata attributes ，您可以使用 filters available 进一步自定义返回的 JSON 内容，例如:

Plugins.Add(new OpenApiFeature
{
    ApiDeclarationFilter = (openApiDoc) => ...,
    OperationFilter = (verb, operation) => ...,
    SchemaFilter = (schema) => ...,
    SchemaPropertyFilter = (openApiProperty) => ...,
});