Epic: Syncing OAS with Kibana code part I

[jloleysens]

Summary

We intend to use this issue to track progress of the work being done to enable Kibana's runtime validation schemas to generate OAS.

The approach

• Leverage existing runtime validation schemas, specifically @kbn/config-schema. It is possible to support other runtime validation schemas, but to start with we will only support @kbn/config-schema.
• Based on this PoC

Tasks

• Make necessary preparations to @kbn/config-schema, extract relevant changes from PoC: Derive OAS 3 from Kibana router #156357
• Introduce the new package where all code for generate OAS will live, furnish with unit tests [HTTP/OAS] @kbn/router-to-openapispec #180683
• Create integration tests (OAS will be served from a core-owned endpoint like /api/oas and treated as internal to begin with) [HTTP/OAS] HTTP API /api/oas #181144
• Support deprecated fields [HTTP/OAS] Support deprecated field #181240
• Support providing different content types for responses [HTTP/OAS] Support specifying content types #181697
• Announce that teams can start updating their schemas and see resulting OAS #181991
• [OAS] Create and commit OAS bundle #181992
• Add support for recursive schemas #182910
• Support tags #183935
• Add operations tagging for more intentional grouping of APIs #182649
• Improve support for enums #182658
• Create a serverless bundle #184719
• Add support for more detailed descriptions of APIs #182779
• [HTTP/OAS] Support deprecated operations #186003

Future tasks

• Support experimental APIs #181995
• [OAS] Support discriminator #181994
• [OAS] Support examples #188926

[elasticmachine]

Pinging @elastic/kibana-core (Team:Core)

[jloleysens]

Milestone

Teams can start providing response schemas and testing the OAS generated from @kbn/config-schema schemas. Core has started with the /api/status, see here. Note: at the moment it is possible to generate OAS using @kbn/config-schema.

We have added:

• The ability to add request and response schemas sufficient for OAS

  • Routes

    kibana/packages/core/http/core-http-server/src/router/route_validator.ts

    Line 147 in 0682fd3

    export interface RouteValidatorRequestAndResponses<P, Q, B> {

  • Versioned routes

    kibana/packages/core/http/core-http-server/src/versioning/types.ts

    Line 215 in 0682fd3

    export interface VersionedRouteValidation<P, Q, B> {

• The ability to add OAS metadata to @kbn/config-schema such that schemas can be documented. See the this example.