Skip to content

Commit

Permalink
[8.x] Improves Lists API docs content (elastic#192504) (elastic#204707)
Browse files Browse the repository at this point in the history
# Backport

This will backport the following commits from `main` to `8.x`:
- [Improves Lists API docs content
(elastic#192504)](elastic#192504)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT
[{"author":{"name":"natasha-moore-elastic","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-09-17T11:24:07Z","message":"Improves
Lists API docs content (elastic#192504)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#32
by\r\nimproving the Lists API docs content. Adds missing and improves
existing\r\noperation summaries and operation descriptions to adhere to
our
[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\nNote:
Couldn’t add description for the GET /api/lists/privileges\r\noperation,
since it's not documented in [ESS
API\r\ndocs](https://www.elastic.co/guide/en/security/8.15/security-apis.html).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"5c5897966ab0d6caaba64d943d91d0485dde16f2","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport:skip","v9.0.0","docs","Team:Detections
and Resp","Team: SecuritySolution","APIDocs","Team:Detection Rule
Management","Team:Detection
Engine"],"number":192504,"url":"https://github.com/elastic/kibana/pull/192504","mergeCommit":{"message":"Improves
Lists API docs content (elastic#192504)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#32
by\r\nimproving the Lists API docs content. Adds missing and improves
existing\r\noperation summaries and operation descriptions to adhere to
our
[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\nNote:
Couldn’t add description for the GET /api/lists/privileges\r\noperation,
since it's not documented in [ESS
API\r\ndocs](https://www.elastic.co/guide/en/security/8.15/security-apis.html).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"5c5897966ab0d6caaba64d943d91d0485dde16f2"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/192504","number":192504,"mergeCommit":{"message":"Improves
Lists API docs content (elastic#192504)\n\n## Summary\r\n\r\nResolves
elastic/security-docs-internal#32
by\r\nimproving the Lists API docs content. Adds missing and improves
existing\r\noperation summaries and operation descriptions to adhere to
our
[OAS\r\nstandards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs).\r\n\r\nNote:
Couldn’t add description for the GET /api/lists/privileges\r\noperation,
since it's not documented in [ESS
API\r\ndocs](https://www.elastic.co/guide/en/security/8.15/security-apis.html).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<[email protected]>","sha":"5c5897966ab0d6caaba64d943d91d0485dde16f2"}}]}]
BACKPORT-->

---------

Co-authored-by: kibanamachine <[email protected]>
  • Loading branch information
natasha-moore-elastic and kibanamachine authored Dec 18, 2024
1 parent 9d6cc07 commit 95b08a5
Show file tree
Hide file tree
Showing 23 changed files with 344 additions and 86 deletions.
69 changes: 49 additions & 20 deletions oas_docs/output/kibana.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -18194,6 +18194,10 @@ paths:
- Fleet uninstall tokens
/api/lists:
delete:
description: |
Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- description: List's `id` value
Expand Down Expand Up @@ -18253,10 +18257,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Deletes a list
summary: Delete a list
tags:
- Security Lists API
get:
description: Get the details of a list using the list ID.
operationId: ReadList
parameters:
- description: List's `id` value
Expand Down Expand Up @@ -18304,10 +18309,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Retrieves a list using its id field
summary: Get list details
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list using the list ID.
operationId: PatchList
requestBody:
content:
Expand Down Expand Up @@ -18371,10 +18377,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Patches a list
summary: Patch a list
tags:
- Security Lists API
post:
description: Create a new list.
operationId: CreateList
requestBody:
content:
Expand Down Expand Up @@ -18445,10 +18452,14 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Creates a list
summary: Create a list
tags:
- Security Lists API
put:
description: |
Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateList
requestBody:
content:
Expand Down Expand Up @@ -18514,11 +18525,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Updates a list
summary: Update a list
tags:
- Security Lists API
/api/lists/_find:
get:
description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
operationId: FindLists
parameters:
- description: The page number to return
Expand Down Expand Up @@ -18620,11 +18632,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Finds lists
summary: Get lists
tags:
- Security Lists API
/api/lists/index:
delete:
description: Delete the `.lists` and `.items` data streams.
operationId: DeleteListIndex
responses:
'200':
Expand Down Expand Up @@ -18670,10 +18683,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Deletes list data streams
summary: Delete list data streams
tags:
- Security Lists API
get:
description: Verify that `.lists` and `.items` data streams exist.
operationId: ReadListIndex
responses:
'200':
Expand Down Expand Up @@ -18722,10 +18736,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Get list data stream existence status
summary: Get status of list data streams
tags:
- Security Lists API
post:
description: Create `.lists` and `.items` data streams in the relevant space.
operationId: CreateListIndex
responses:
'200':
Expand Down Expand Up @@ -18771,11 +18786,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Creates necessary list data streams
summary: Create list data streams
tags:
- Security Lists API
/api/lists/items:
delete:
description: Delete a list item using its `id`, or its `list_id` and `value` fields.
operationId: DeleteListItem
parameters:
- description: Required if `list_id` and `value` are not specified
Expand Down Expand Up @@ -18850,10 +18866,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Deletes a list item
summary: Delete a list item
tags:
- Security Lists API
get:
description: Get the details of a list item.
operationId: ReadListItem
parameters:
- description: Required if `list_id` and `value` are not specified
Expand Down Expand Up @@ -18917,10 +18934,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Gets a list item
summary: Get a list item
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list item using the list item ID.
operationId: PatchListItem
requestBody:
content:
Expand Down Expand Up @@ -18986,10 +19004,16 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Patches a list item
summary: Patch a list item
tags:
- Security Lists API
post:
description: |
Create a list item and associate it with the specified list.

All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
operationId: CreateListItem
requestBody:
content:
Expand Down Expand Up @@ -19056,10 +19080,14 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Creates a list item
summary: Create a list item
tags:
- Security Lists API
put:
description: |
Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateListItem
requestBody:
content:
Expand Down Expand Up @@ -19119,12 +19147,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Updates a list item
summary: Update a list item
tags:
- Security Lists API
/api/lists/items/_export:
post:
description: Exports list item values from the specified list
description: Export list item values from the specified list.
operationId: ExportListItems
parameters:
- description: List's id to export
Expand Down Expand Up @@ -19174,11 +19202,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Exports list items
summary: Export list items
tags:
- Security Lists API
/api/lists/items/_find:
get:
description: Get all list items in the specified list.
operationId: FindListItems
parameters:
- description: List's id
Expand Down Expand Up @@ -19286,13 +19315,13 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Finds list items
summary: Get list items
tags:
- Security Lists API
/api/lists/items/_import:
post:
description: |
Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.

You can import items to a new or existing list.
operationId: ImportListItems
Expand Down Expand Up @@ -19385,7 +19414,7 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Imports list items
summary: Import list items
tags:
- Security Lists API
/api/lists/privileges:
Expand Down Expand Up @@ -19435,7 +19464,7 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Gets list privileges
summary: Get list privileges
tags:
- Security Lists API
/api/ml/saved_objects/sync:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: CreateList
x-codegen-enabled: true
summary: Creates a list
summary: Create a list
description: Create a new list.
requestBody:
description: List's properties
required: true
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: CreateListIndex
x-codegen-enabled: true
summary: Creates necessary list data streams
summary: Create list data streams
description: Create `.lists` and `.items` data streams in the relevant space.
responses:
200:
description: Successful response
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,13 @@ paths:
x-labels: [serverless, ess]
operationId: CreateListItem
x-codegen-enabled: true
summary: Creates a list item
summary: Create a list item
description: |
Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
requestBody:
description: List item's properties
required: true
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,11 @@ paths:
x-labels: [serverless, ess]
operationId: DeleteList
x-codegen-enabled: true
summary: Deletes a list
summary: Delete a list
description: |
Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
parameters:
- name: id
in: query
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: DeleteListIndex
x-codegen-enabled: true
summary: Deletes list data streams
summary: Delete list data streams
description: Delete the `.lists` and `.items` data streams.
responses:
200:
description: Successful response
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: DeleteListItem
x-codegen-enabled: true
summary: Deletes a list item
summary: Delete a list item
description: Delete a list item using its `id`, or its `list_id` and `value` fields.
parameters:
- name: id
in: query
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: ExportListItems
x-codegen-enabled: true
summary: Exports list items
description: Exports list item values from the specified list
summary: Export list items
description: Export list item values from the specified list.
parameters:
- name: list_id
in: query
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: FindListItems
x-codegen-enabled: true
summary: Finds list items
summary: Get list items
description: Get all list items in the specified list.
parameters:
- name: list_id
in: query
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: FindLists
x-codegen-enabled: true
summary: Finds lists
summary: Get lists
description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
parameters:
- name: page
in: query
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ paths:
x-labels: [serverless, ess]
operationId: ImportListItems
x-codegen-enabled: true
summary: Imports list items
summary: Import list items
description: |
Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
You can import items to a new or existing list.
requestBody:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: PatchList
x-codegen-enabled: true
summary: Patches a list
summary: Patch a list
description: Update specific fields of an existing list using the list ID.
requestBody:
description: List's properties
required: true
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: PatchListItem
x-codegen-enabled: true
summary: Patches a list item
summary: Patch a list item
description: Update specific fields of an existing list item using the list item ID.
requestBody:
description: List item's properties
required: true
Expand Down
Loading

0 comments on commit 95b08a5

Please sign in to comment.