[OAS] Support examples (and more) by jloleysens · Pull Request #212495 · elastic/kibana

jloleysens · 2025-02-26T10:26:36Z

Summary

Adds the ability to merge in an arbitrary OAS operation object (search spec for "operation object") in code generated OAS.

This enables us to write examples next to the code:

// Inside the router declaration
  router.post(
    {
      path: `${BASE_ALERTING_API_PATH}/rule/{id?}`,
      security: DEFAULT_ALERTING_ROUTE_SECURITY,
      options: {
        access: 'public',
        summary: `Create a rule`,
        tags: ['oas-tag:alerting'],
        // NEW 👇🏻: this file can contain operation-level OAS and will merge/override anything that we auto generate
        oasOperationObject: () => path.join(__dirname, 'create_rule.examples.yaml'),
        // ☝🏻 can also be a TS-checked OpenAPIV3.OperationObject

Tested with create rule example overlay (gist) and bump

Docs

Added developer guide docs to https://docs.elastic.dev/kibana-dev-docs/genereating-oas-for-http-apis#2-route-definitions

images

TO DO

Document the feature in TS
Document feature in dev docs
Add tests

src/platform/packages/shared/kbn-router-to-openapispec/src/merge_operation_with_schema_file.ts

jloleysens · 2025-02-26T10:29:01Z

src/platform/packages/shared/kbn-router-to-openapispec/src/generate_oas.ts

 }

-export const generateOpenApiDocument = (
+export const generateOpenApiDocument = async (


Needed to touch other files bc of async poisoning

package.json

...ck/platform/plugins/shared/alerting/server/routes/rule/apis/create/create_rule.examples.yaml

x-pack/platform/plugins/shared/alerting/server/routes/rule/apis/create/create_rule_route.ts

jloleysens · 2025-02-26T20:34:15Z

/ci

jloleysens · 2025-02-27T11:03:43Z

/ci

…t --include-path /api/status --include-path /api/alerting/rule/ --include-path /api/alerting/rules --include-path /api/actions --include-path /api/security/role --include-path /api/spaces --include-path /api/fleet --include-path /api/dashboards --update'

jloleysens · 2025-03-03T10:53:50Z

/ci

jloleysens · 2025-03-03T16:23:53Z

/ci

flash1293 · 2025-03-04T15:59:04Z

@jloleysens I know I'm late to this, but did you think about specifying the examples in the typescript code instead of a separate yaml file? This way it could be type-checked automatically

elasticmachine · 2025-03-06T08:24:30Z

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

elasticmachine · 2025-03-06T08:24:32Z

Pinging @elastic/response-ops (Team:ResponseOps)

afharo

LGTM! I just added a question regarding the existence of any helpers (or guide) to create a template to the example files. Since they are manual, I'd like to be able to make it a bit more "guided" the part of providing all the fields to fill.

afharo · 2025-03-11T10:53:52Z

...ck/platform/plugins/shared/alerting/server/routes/rule/apis/create/create_rule.examples.yaml

@@ -0,0 +1,31 @@
+# Because of where this file is linked to the code you are in


Q: Is there a way to create the template of these files via a command?

I worry that documenting examples might be too complex that ends up not being used. WDYT?

Yeah, that's a good question. I'll expand our existing tutorial to guide devs through this. Perhaps some tooling could come later!

lcawl

Docs output LGTM! Thanks for removing the need to accomplish this via overlays, which were much more fragile

cnasikas

We are in the process of slowly moving the schema of the parameters of each rule type in the @kbn/response-ops-rule-params (src/platform/packages/shared/response-ops/rule_params). The route uses the createBodySchema which in turn imports the schemas from the package (x-pack/platform/plugins/shared/alerting/common/routes/rule/apis/create/schemas/v1.ts). Should we also put the examples in the package (each rule type folder has its example.yml)?

jloleysens · 2025-03-13T11:10:31Z

@cnasikas , colocating the examples with the most relevant code makes sense... In your case I'm not sure whether that is route (I guess it contains some business logic that inform the examples) or the actual schemas... I'd lean toward colocating with schemas. Would that work with your workflow?

cnasikas · 2025-03-13T11:13:29Z

Thanks @jloleysens. Yes, I also lean toward colocating with the schemas (as described in my previous comment), if you don't mind.

…t --include-path /api/status --include-path /api/alerting/rule/ --include-path /api/alerting/rules --include-path /api/actions --include-path /api/security/role --include-path /api/spaces --include-path /api/fleet --include-path /api/dashboards --update'

jloleysens · 2025-03-14T09:49:51Z

oas_docs/bundle.json

bundle*.json and output/*yaml snapshot files here are the source of most newlines.

jloleysens · 2025-03-14T09:50:40Z

dev_docs/tutorials/generating_oas_for_http_apis.mdx

+of your API. See the [bump.sh documentation](https://docs.bump.sh/guides/openapi/specification/v3.1/data-models/examples/)
+for more information on how examples will be shown to end users.
+
+To add examples to the endpoint we created above you could do the following:


Recommending the code-first approach to keep consistent with the rest of the platform provided approach to OAS.

jloleysens · 2025-03-14T09:51:59Z

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

  'validate' | 'options'
 > & {
-  options?: Omit<
+  options?: Pick<


Not needed for this PR, but converted this type subset selection from blocklist to allowlist for stricter control of the interface we are exposing.

jloleysens · 2025-03-14T09:53:14Z

oas_docs/overlays/alerting.overlays.yaml

  title: Overlays for the alerting rule examples and parameters
  version: 0.0.1
 actions:
-  # Add some alerting API examples


Moved closer to respective ResponseOps code

elasticmachine · 2025-03-14T12:25:36Z

💚 Build Succeeded

Buildkite Build
Commit: a707aee

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`@kbn/response-ops-rule-params`	8	9	+1

Unknown metric groups

API count

id	before	after	diff
`@kbn/core-http-server`	571	572	+1
`@kbn/response-ops-rule-params`	8	9	+1
total			+2

History

💔 Build #283833 failed 10043fd
💔 Build #283818 failed 53efeee
💚 Build #282907 succeeded 03388fa
💚 Build #282621 succeeded d507451
💚 Build #281806 succeeded fcc6e18

cc @jloleysens

cnasikas

LGTM!

## Summary Close elastic#188926 Adds the ability to merge in an arbitrary OAS operation object (search [spec](https://swagger.io/specification/) for "operation object") in code generated OAS. This enables us to write examples next to the code: <img width="306" alt="Screenshot 2025-02-26 at 11 24 00" src="https://github.com/user-attachments/assets/5df92ae9-c8c5-4797-8b7c-764e937e84e9" /> ```ts // Inside the router declaration router.post( { path: `${BASE_ALERTING_API_PATH}/rule/{id?}`, security: DEFAULT_ALERTING_ROUTE_SECURITY, options: { access: 'public', summary: `Create a rule`, tags: ['oas-tag:alerting'], // NEW 👇🏻: this file can contain operation-level OAS and will merge/override anything that we auto generate oasOperationObject: () => path.join(__dirname, 'create_rule.examples.yaml'), // ☝🏻 can also be a TS-checked OpenAPIV3.OperationObject ``` Tested with create rule example overlay ([gist](https://gist.github.com/jloleysens/dc643522a3f58dc2aed3dcef966b42df)) and bump <img width="1236" alt="Screenshot 2025-02-26 at 11 45 57" src="https://github.com/user-attachments/assets/c21b466a-ddab-49ce-b4ba-a04fd0e6c1b7" /> ## Docs Added developer guide docs to https://docs.elastic.dev/kibana-dev-docs/genereating-oas-for-http-apis#2-route-definitions <details> <summary>images</summary> <img width="799" alt="Screenshot 2025-03-13 at 13 02 31" src="https://github.com/user-attachments/assets/e89b2c5a-1984-4672-a40b-b492581e690f" /> <img width="819" alt="Screenshot 2025-03-13 at 13 02 39" src="https://github.com/user-attachments/assets/1375a25a-4d91-46b4-8ce5-42c763657d96" /> </details> ### TO DO - [x] Document the feature in TS - [x] Document feature in dev docs - [x] Add tests --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

jloleysens added 7 commits February 26, 2025 11:17

attempt 1 at a layout for OAS examples

b20a42b

added support for merging files

1e5af2a

comment out the rules create overlay

277169c

await

1232c10

add new type

c23f4ef

link to file from create rule

58a9e60

added @apidevtools/json-schema-ref-parser

bb15822

jloleysens requested a review from lcawl February 26, 2025 10:26

woops

74c53ba

jloleysens commented Feb 26, 2025

View reviewed changes

...ck/platform/plugins/shared/alerting/server/routes/rule/apis/create/create_rule.examples.yaml Outdated Show resolved Hide resolved

jloleysens commented Feb 26, 2025

View reviewed changes

x-pack/platform/plugins/shared/alerting/server/routes/rule/apis/create/create_rule_route.ts Outdated Show resolved Hide resolved

jloleysens changed the title ~~[OAS] Support examples~~ [OAS] Support examples (and more) Feb 26, 2025

[CI] Auto-commit changed files from 'node scripts/notice'

01805e1

kibanamachine and others added 2 commits February 27, 2025 11:19

Merge branch 'main' into oas/support-examples

bc1c1d9

[CI] Auto-commit changed files from 'make api-docs'

3e1ddb7

jloleysens added 2 commits March 4, 2025 10:25

Merge branch 'main' into oas/support-examples

5071537

update renovate.json

e392720

flash1293 mentioned this pull request Mar 4, 2025

🌊 Streams: Prepare API for publishing #213127

Merged

jloleysens requested a review from a team as a code owner March 6, 2025 08:24

afharo approved these changes Mar 11, 2025

View reviewed changes

lcawl approved these changes Mar 11, 2025

View reviewed changes

cnasikas reviewed Mar 12, 2025

View reviewed changes

Merge branch 'main' into oas/support-examples

62b8249

jloleysens added 3 commits March 13, 2025 13:02

update docs

09c745a

fix where the examples are linked in for the versioned router

fce5f75

move response ops files

7d3bced

jloleysens force-pushed the oas/support-examples branch from 03388fa to 7d3bced Compare March 13, 2025 15:43

kibanamachine and others added 4 commits March 13, 2025 15:57

[CI] Auto-commit changed files from 'node scripts/notice'

68554f8

[CI] Auto-commit changed files from 'make api-docs'

10043fd

clean up code, types and comments

e8b733b

jloleysens requested a review from a team as a code owner March 14, 2025 09:48

miltonhultgren approved these changes Mar 14, 2025

View reviewed changes

jloleysens commented Mar 14, 2025

View reviewed changes

jloleysens self-assigned this Mar 14, 2025

Merge branch 'main' into oas/support-examples

a707aee

cnasikas approved these changes Mar 14, 2025

View reviewed changes

jloleysens merged commit 5e90e55 into elastic:main Mar 14, 2025
9 checks passed

jloleysens deleted the oas/support-examples branch March 14, 2025 13:56

kibanamachine added the v9.1.0 label Mar 14, 2025

afharo mentioned this pull request Jul 25, 2025

Upgrade @apidevtools/json-schema-ref-parser #229184

Merged

2 tasks

		@@ -0,0 +1,31 @@
		# Because of where this file is linked to the code you are in

Conversation

jloleysens commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Docs

TO DO

Uh oh!

Uh oh!

jloleysens Feb 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jloleysens commented Feb 26, 2025

Uh oh!

jloleysens commented Feb 27, 2025

Uh oh!

jloleysens commented Mar 3, 2025

Uh oh!

jloleysens commented Mar 3, 2025

Uh oh!

flash1293 commented Mar 4, 2025

Uh oh!

elasticmachine commented Mar 6, 2025

Uh oh!

elasticmachine commented Mar 6, 2025

Uh oh!

afharo left a comment

Choose a reason for hiding this comment

Uh oh!

afharo Mar 11, 2025

Choose a reason for hiding this comment

Uh oh!

jloleysens Mar 13, 2025

Choose a reason for hiding this comment

Uh oh!

lcawl left a comment

Choose a reason for hiding this comment

Uh oh!

cnasikas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jloleysens commented Mar 13, 2025

Uh oh!

cnasikas commented Mar 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jloleysens Mar 14, 2025

Choose a reason for hiding this comment

Uh oh!

jloleysens Mar 14, 2025

Choose a reason for hiding this comment

Uh oh!

jloleysens Mar 14, 2025

Choose a reason for hiding this comment

Uh oh!

jloleysens Mar 14, 2025

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Mar 14, 2025

💚 Build Succeeded

Metrics [docs]

Public APIs missing comments

API count

History

Uh oh!

cnasikas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

jloleysens commented Feb 26, 2025 •

edited

Loading

cnasikas left a comment •

edited

Loading

cnasikas commented Mar 13, 2025 •

edited

Loading