github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-22 00:45:43 -04:00
Code Issues Projects Releases Packages Wiki Activity
kibana/oas_docs/examples
History
Exact
Jean-Louis Leysens 5e90e557cf
[OAS] Support examples (and more) (#212495) 
## Summary

Close https://github.com/elastic/kibana/issues/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>
2025-03-14 14:56:28 +01:00
..
copy_saved_objects_request1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
copy_saved_objects_request2.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
copy_saved_objects_response1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
copy_saved_objects_response2.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
copy_saved_objects_response3.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
copy_saved_objects_response4.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
create_email_connector_request.yaml
create_email_connector_response.yaml
create_es_query_esql_rule_request.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_es_query_esql_rule_response.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_es_query_kql_rule_request.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_es_query_kql_rule_response.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_es_query_rule_request.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_es_query_rule_response.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_index_connector_request.yaml
create_index_connector_response.yaml
create_index_threshold_rule_request.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_index_threshold_rule_response.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_role_request1.yaml [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) 2024-10-25 10:13:57 -07:00
create_role_request2.yaml [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) 2024-10-25 10:13:57 -07:00
create_role_request3.yaml [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) 2024-10-25 10:13:57 -07:00
create_role_request4.yaml [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) 2024-10-25 10:13:57 -07:00
create_space_request.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
create_tracking_containment_rule_request.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_tracking_containment_rule_response.yaml [OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
create_webhook_connector_request.yaml
create_webhook_connector_response.yaml
create_xmatters_connector_request.yaml
create_xmatters_connector_response.yaml
disable_legacy_url_request1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
get_connector_response.yaml
get_connector_types_generativeai_response.yaml [DOCS] Remove inference connector docs (#198633) 2024-11-12 11:56:37 -06:00
get_connectors_response.yaml
get_role_response1.yaml [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) 2024-10-25 10:13:57 -07:00
get_roles_response1.yaml [OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527) 2024-10-25 10:13:57 -07:00
get_space_response.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
get_spaces_response1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
get_spaces_response2.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
resolve_copy_saved_objects_request1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
resolve_copy_saved_objects_request2.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
resolve_copy_saved_objects_response1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
resolve_copy_saved_objects_response2.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
run_cases_webhook_connector_request.yaml
run_cases_webhook_connector_response.yaml
run_email_connector_request.yaml
run_email_connector_response.yaml
run_index_connector_request.yaml
run_index_connector_response.yaml
run_jira_connector_request.yaml
run_jira_connector_response.yaml
run_pagerduty_connector_request.yaml
run_pagerduty_connector_response.yaml
run_server_log_connector_request.yaml
run_server_log_connector_response.yaml
run_servicenow_itom_connector_request.yaml
run_servicenow_itom_connector_response.yaml
run_slack_api_connector_request.yaml
run_slack_api_connector_response.yaml
run_swimlane_connector_request.yaml
run_swimlane_connector_response.yaml
update_index_connector_request.yaml
update_saved_objects_spaces_request1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
update_saved_objects_spaces_response1.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00
update_space_request.yaml [DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333) 2024-10-18 14:03:06 -05:00