elastic/kibana

[OAS] Allow custom sorting/post-processing of OAS properties generated from router

Open

#233,797 创建于 2025年9月2日

在 GitHub 查看
 (1 评论) (0 反应) (0 负责人)TypeScript (19,065 star) (8,021 fork)batch import
Feature:OASTeam:Coreenhancementgood first issue

描述

The OAS converter currently emits properties in the order returned by joi-to-json, with no way to apply custom sorting for user-facing OAS docs.

Current behavior:

  • Properties appear in the order provided by joi-to-json.
  • OpenAPI/OAS has no built-in support for custom field ordering.
  • Modifying the generated YAML is possible but will be overwritten whenever the generator runs.

Possible solutions

  • Add a post-processing hook (similar to postProcessMutations in parse.ts) or an extension point (e.g., ObjectTypeOptionsMeta) so we can reorder properties in the final OAS output (not limited to alphabetical sorting).
  • Alternatively explore safe ways to modify final YAML output without being clobbered by regeneration.
  • Something completely different

References:

Expected outcome:

  • A pluggable mechanism to apply custom sorting or other transformations to generated OAS properties before writing the final spec.

贡献者指南

技术栈
typescriptnodejsrest api
领域
backendapi
议题类型
feature
难度面向新贡献者的预计实现难度，1 表示很小改动，5 表示专家级工作。
3
预计时间有经验贡献者完成调查、实现、测试并准备 pull request 的粗略时间范围。
3-5 days
活动状态议题当前的可参与程度：新鲜、活跃、陈旧、阻塞或等待维护者输入。
fresh
清晰度议题是否清楚说明期望改动、验收标准和下一步。
clear
前置要求
TypeScriptOpenAPI SpecificationKibana codebase navigation
新手友好度1-100 的估计分数，表示该议题对首次贡献者的友好程度。
30
研究方向
Examine the postProcessMutations hook in parse.ts (https://github.com/elastic/kibana/blob/6f6a42d492aea851c3aaf68830e667491a4660fe/src/platform/packages/shared/kbn router to openapispec/src/oas converter/kbn config schema/parse.ts#L38 L52) to understand its pattern. Investigate how OAS properties are currently generated from joi to json and identify where a custom sorting/post processing hook could be inserted. Propose a design for a pluggable mechanism, possibly using a function or class that receives the generated spec and allows transformations. Consider edge cases like preserving order for required fields or handling nested properties. No implementation needed; focus on design and identifying potential extension points.