[OAS] Allow custom sorting/post-processing of OAS properties generated from router · elastic/kibana#233797 | Good First Issue

(1 comment) (0 reactions) (0 assignees)TypeScript (8,021 forks)batch import

Feature:OASTeam:Coreenhancementgood first issue

Repository metrics

Stars: (19,065 stars)
PR merge metrics: (Avg merge 2d 3h) (1,000 merged PRs in 30d)

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:

Example hook: parse.ts postProcessMutations — 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

Expected outcome:

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

Contributor guide

Research direction: Implement a post processing hook similar to the existing `postProcessMutations` in `parse.ts` to allow custom ordering of OAS properties.
Tech stack: typescript
Domain: apibackend
Issue type: Feature
Difficulty: 3
Estimated time: 1-2 days
Activity status: Active
Clarity: Clear
Prerequisites: TypeScriptOpenAPI/Swagger
Newbie friendliness: 50