[Security Assistant] Aligning API Schemas

[spong]

Summary

This PR aims to address #183825 to ensure all our public API's have a corresponding OpenAPI spec and to ensure that they are documented as intended.

I've updated the kbn-elastic-assistant-common yarn openapi:bundle script to generate both ess and serverless artifacts (as per this issue, which are now created within the package (instead of target), and so are checked in to x-pack/packages/kbn-elastic-assistant-common/docs/openapi/.

This also includes:

• Create OpenAPI specs for the endpoints listed above (see issue).
  • They had already existed
• Check if there are any other public endpoints that you own that don't have OpenAPI specs and add them to the list above.
  • All endpoints (public/internal) had specs, but did need to update the path's to make sure they were consistent with what was registered.
• Make sure the specs you add are valid OpenAPI documents.
• Make sure the specs you add match the actual API contract defined in the code.
• Mark the endpoints as available in ESS, or Serverless, or in both offerings.

---

Initial evaluation of routes listed as missing specs in #183825:

• POST /api/elastic_assistant/current_user/conversations/{id}/messages
  Latest/Actual Route: /internal/elastic_assistant/current_user/conversations/{id}/messages
  Route Handler:

  kibana/x-pack/plugins/elastic_assistant/server/routes/user_conversations/append_conversation_messages_route.ts

  Line 22 in bae84d4

  export const appendConversationMessageRoute = (router: ElasticAssistantPluginRouter) => {

  
  Schema:

  kibana/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml

  Lines 151 to 191 in bae84d4

  	/internal/elastic_assistant/conversations/{id}/messages:
  	post:
  	operationId: AppendConversationMessage
  	x-codegen-enabled: true
  	description: Append a message to the conversation
  	summary: Append a message to the conversation
  	tags:
  	- Conversation API
  	parameters:
  	- name: id
  	in: path
  	required: true
  	description: The conversation's `id` value.
  	schema:
  	$ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
  	requestBody:
  	required: true
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationMessageCreateProps'
  	responses:
  	200:
  	description: Indicates a successful call.
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationResponse'
  	400:
  	description: Generic Error
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	statusCode:
  	type: number
  	error:
  	type: string
  	message:
  	type: string

• POST /api/elastic_assistant/current_user/conversations
  Updated Route: /api/security_ai_assistant/current_user/conversations
  Route Handler:

  kibana/x-pack/plugins/elastic_assistant/server/routes/user_conversations/create_route.ts

  Line 21 in 1d4e9b9

  export const createConversationRoute = (router: ElasticAssistantPluginRouter): void => {

  
  Schema:

  kibana/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml

  Lines 6 to 39 in bae84d4

  	/internal/elastic_assistant/conversations:
  	post:
  	operationId: CreateConversation
  	x-codegen-enabled: true
  	description: Create a conversation
  	summary: Create a conversation
  	tags:
  	- Conversation API
  	requestBody:
  	required: true
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationCreateProps'
  	responses:
  	200:
  	description: Indicates a successful call.
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationResponse'
  	400:
  	description: Generic Error
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	statusCode:
  	type: number
  	error:
  	type: string
  	message:
  	type: string

• GET /api/elastic_assistant/current_user/conversations/_find
  Updated Route: /api/security_ai_assistant/current_user/conversations/_find
  Route Handler:

  kibana/x-pack/plugins/elastic_assistant/server/routes/user_conversations/find_route.ts

  Line 26 in 1d4e9b9

  export const findUserConversationsRoute = (router: ElasticAssistantPluginRouter) => {

  
  Schema:

  kibana/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml

  Lines 94 to 180 in 1b872fb

  	/internal/elastic_assistant/conversations/current_user/_find:
  	get:
  	operationId: FindCurrentUserConversations
  	x-codegen-enabled: true
  	description: Finds current user conversations that match the given query.
  	summary: Finds current user conversations that match the given query.
  	tags:
  	- Conversations API
  	parameters:
  	- name: 'fields'
  	in: query
  	required: false
  	schema:
  	type: array
  	items:
  	type: string
  	- name: 'filter'
  	in: query
  	description: Search query
  	required: false
  	schema:
  	type: string
  	- name: 'sort_field'
  	in: query
  	description: Field to sort by
  	required: false
  	schema:
  	$ref: '#/components/schemas/FindConversationsSortField'
  	- name: 'sort_order'
  	in: query
  	description: Sort order
  	required: false
  	schema:
  	$ref: '../common_attributes.schema.yaml#/components/schemas/SortOrder'
  	- name: 'page'
  	in: query
  	description: Page number
  	required: false
  	schema:
  	type: integer
  	minimum: 1
  	default: 1
  	- name: 'per_page'
  	in: query
  	description: Conversations per page
  	required: false
  	schema:
  	type: integer
  	minimum: 0
  	default: 20
  	responses:
  	200:
  	description: Successful response
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	page:
  	type: integer
  	perPage:
  	type: integer
  	total:
  	type: integer
  	data:
  	type: array
  	items:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationResponse'
  	required:
  	- page
  	- perPage
  	- total
  	- data
  	400:
  	description: Generic Error
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	statusCode:
  	type: number
  	error:
  	type: string
  	message:
  	type: string

• DELETE /api/elastic_assistant/current_user/conversations/{id}
  Updated Route: /api/security_ai_assistant/current_user/conversations/{id}
  Route Handler:

  kibana/x-pack/plugins/elastic_assistant/server/routes/user_conversations/delete_route.ts

  Line 19 in 1d5cf48

  export const deleteConversationRoute = (router: ElasticAssistantPluginRouter) => {

  
  Schema:

  kibana/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml

  Lines 116 to 149 in bae84d4

  	delete:
  	operationId: DeleteConversation
  	x-codegen-enabled: true
  	description: Deletes a single conversation using the `id` field.
  	summary: Deletes a single conversation using the `id` field.
  	tags:
  	- Conversation API
  	parameters:
  	- name: id
  	in: path
  	required: true
  	description: The conversation's `id` value.
  	schema:
  	$ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
  	responses:
  	200:
  	description: Indicates a successful call.
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationResponse'
  	400:
  	description: Generic Error
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	statusCode:
  	type: number
  	error:
  	type: string
  	message:
  	type: string

• GET /api/elastic_assistant/current_user/conversations/{id}
  Updated Route: /api/security_ai_assistant/current_user/conversations/{id}
  Route Handler:

  kibana/x-pack/plugins/elastic_assistant/server/routes/user_conversations/read_route.ts

  Line 21 in 1d5cf48

  export const readConversationRoute = (router: ElasticAssistantPluginRouter) => {

  
  Schema:

  kibana/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml

  Lines 42 to 75 in bae84d4

  	get:
  	operationId: ReadConversation
  	x-codegen-enabled: true
  	description: Read a single conversation
  	summary: Read a single conversation
  	tags:
  	- Conversations API
  	parameters:
  	- name: id
  	in: path
  	required: true
  	description: The conversation's `id` value.
  	schema:
  	$ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
  	responses:
  	200:
  	description: Indicates a successful call.
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationResponse'
  	400:
  	description: Generic Error
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	statusCode:
  	type: number
  	error:
  	type: string
  	message:
  	type: string

• PUT /api/elastic_assistant/current_user/conversations/{id}
  Updated Route: /api/security_ai_assistant/current_user/conversations/{id}
  Route Handler:

  kibana/x-pack/plugins/elastic_assistant/server/routes/user_conversations/update_route.ts

  Line 24 in 1d5cf48

  export const updateConversationRoute = (router: ElasticAssistantPluginRouter) => {

  
  Schema:

  kibana/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml

  Lines 76 to 115 in bae84d4

  	put:
  	operationId: UpdateConversation
  	x-codegen-enabled: true
  	description: Update a single conversation
  	summary: Update a conversation
  	tags:
  	- Conversation API
  	parameters:
  	- name: id
  	in: path
  	required: true
  	description: The conversation's `id` value.
  	schema:
  	$ref: '../common_attributes.schema.yaml#/components/schemas/NonEmptyString'
  	requestBody:
  	required: true
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationUpdateProps'
  	responses:
  	200:
  	description: Indicates a successful call.
  	content:
  	application/json:
  	schema:
  	$ref: './common_attributes.schema.yaml#/components/schemas/ConversationResponse'
  	400:
  	description: Generic Error
  	content:
  	application/json:
  	schema:
  	type: object
  	properties:
  	statusCode:
  	type: number
  	error:
  	type: string
  	message:
  	type: string

To continue with remaining public routes....

[maximpn]

@spong thank you for addressing OpenAPI tasks 👍

I looked through the diff and don't have any concerns regarding OpenAPI specs from general point of view. Though I didn't check that the specs match the implementation. But since generated artefacts are used in the implementation chances the implementation and specs don't match are quite low.

After this PR is merged the PR to enable bundling at pipeline will boil down to .buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh changes.

[YulNaumenko]

LGTM!

[kibana-ci]

💛 Build succeeded, but was flaky

• Buildkite Build
• Commit: e60970b

Failed CI Steps

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/elastic-assistant-common	337	332	-5

Unknown metric groups

API count

id	before	after	diff
@kbn/elastic-assistant-common	363	358	-5

History

• 💔 Build #223360 failed 82e37f9
• 💛 Build #223100 was flaky ab818cc

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @spong

[kibanamachine]

💚 All backports created successfully

Status	Branch	Result
✅	8.15

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation