elastic/kibana

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

Open

#233 797 ouverte le 2 sept. 2025

Voir sur GitHub
 (1 commentaire) (0 réactions) (0 assignés)TypeScript (19 065 stars) (8 021 forks)batch import
Feature:OASTeam:Coreenhancementgood first issue

Description

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.

Guide contributeur

Stack technique
typescriptnodejsrest api
Domaine
backendapi
Type d'issue
feature
DifficultéDifficulté estimée pour un nouveau contributeur, de 1 pour un très petit changement à 5 pour un travail expert.
3
Temps estiméFourchette de temps approximative pour investiguer, implémenter, tester et préparer une pull request.
3-5 days
Statut d'activitéDisponibilité apparente de l'issue : fraîche, active, ancienne, bloquée ou en attente d'un mainteneur.
fresh
ClartéClarté avec laquelle l'issue explique le changement attendu, les critères d'acceptation et la prochaine étape.
clear
Prérequis
TypeScriptOpenAPI SpecificationKibana codebase navigation
Accessibilité débutantScore de 1 à 100 estimant l'accessibilité de cette issue pour un premier contributeur.
30
Direction de recherche
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.