Commit graph

8 commits

Author SHA1 Message Date
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
Lisa Cawley
517063d0a4
[DOCS] Remove inference connector docs (#198633) 2024-11-12 11:56:37 -06:00
Lisa Cawley
02fab7248d
[OpenAPI][DOCS] Add descriptions, examples, responses for role APIs (#195527)
Co-authored-by: Elena Shostak <165678770+elena-shostak@users.noreply.github.com>
2024-10-25 10:13:57 -07:00
Lisa Cawley
2656e5a4ff
[DOCS][OpenAPI] Add descriptions, examples, tags, responses for space APIs (#195333)
Co-authored-by: Elena Shostak <165678770+elena-shostak@users.noreply.github.com>
2024-10-18 14:03:06 -05:00
Yuliia Naumenko
288d41d61e
[Connectors][GenAI] Inference Service Kibana connector (#189027)
## Summary
Resolves https://github.com/elastic/kibana/issues/188043

This PR adds new connector which is define integration with Elastic
Inference Endpoint via [Inference
APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/inference-apis.html)
The lifecycle of the Inference Endpoint are managed by the connector
registered handlers:

- `preSaveHook` -
[create](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-inference-api.html)
new Inference Endpoint in the connector create mode (`isEdit === false`)
and
[delete](https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-inference-api.html)+[create](https://www.elastic.co/guide/en/elasticsearch/reference/current/put-inference-api.html)
in the connector edit mode (`isEdit === true`)
- `postSaveHook` - check if the connector SO was created/updated and if
not removes Inference Endpoint from preSaveHook
- `postDeleteHook` -
[delete](https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-inference-api.html)
Inference Endpoint if connector was deleted.

In the Kibana Stack Management Connectors, its represented with the new
card (Technical preview badge):

<img width="1261" alt="Screenshot 2024-09-27 at 2 11 12 PM"
src="https://github.com/user-attachments/assets/dcbcce1f-06e7-4d08-8b77-0ba4105354f8">

To simplify the future integration with AI Assistants, the Connector
consists from the two main UI parts: provider selector and required
provider settings, which will be always displayed
<img width="862" alt="Screenshot 2024-10-07 at 7 59 09 AM"
src="https://github.com/user-attachments/assets/87bae493-c642-479e-b28f-6150354608dd">

and Additional options, which contains optional provider settings and
Task Type configuration:

<img width="861" alt="Screenshot 2024-10-07 at 8 00 15 AM"
src="https://github.com/user-attachments/assets/2341c034-6198-4731-8ce7-e22e6c6fb20f">


subActions corresponds to the different taskTypes Inference API
supports. Each of the task type has its own Inference Perform params.
Currently added:

- completion & completionStream
- rerank
- text_embedding
- sparse_embedding

Follow up work:

1. Collapse/expand Additional options, when the connector flyout/modal
has AI Assistant as a context (path through the extending context
implementation on the connector framework level)
2. Add support for additional params for Completion subAction to be able
to path functions
3. Add support for tokens usage Dashboard, when inference API will
include the used tokens count in the response
4. Add functionality and UX for migration from existing specific AI
connectors to the Inference connector with proper provider and
completion task
5. Integrate Connector with the AI Assistants

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
Co-authored-by: Steph Milovic <stephanie.milovic@elastic.co>
2024-10-13 15:39:09 -05:00
Lisa Cawley
539ad61d37
[OpenAPI][ResponseOps] Edit descriptions for alerting rule API examples (#194080) 2024-09-27 12:45:44 -04:00
Lisa Cawley
86f9af8243
[OAS][DOCS] Add overlays for connector config and examples (#191791) 2024-09-05 11:19:52 -05:00
Lisa Cawley
e429b73e5a
[OAS][DOCS] Use automated alerting rule API documentation (#190205)
Co-authored-by: Jean-Louis Leysens <jeanlouis.leysens@elastic.co>
2024-08-15 17:07:56 -05:00