[Security Solution] Make existing OpenAPI specs for Entity Analytics API documentation-ready

[maximpn]

Epic: https://github.com/elastic/security-team/issues/9693

Deadline: Sep 24, 2024 (see milestones in https://github.com/elastic/security-team/issues/9400)

Summary

As part of the Serverless project, we need to make sure OpenAPI specs for all public Entity Analytics API endpoints are polished and ready to be published on a documentation website. Please look for more context in the epic, and please find below what needs to be done exactly.

API endpoints

The following public API endpoints were discovered:

• GET /api/asset_criticality
• POST /api/asset_criticality
• DELETE /api/asset_criticality
• POST /api/asset_criticality/bulk
• POST /api/asset_criticality/list

To do

For all the Entity Analytics API endpoints (including those above), in the corresponding OpenAPI specification files, please:

• Add summaries for:
  • API endpoints
  • HTTP methods
• Add descriptions for:
  • API endpoints
  • HTTP methods
  • endpoint's parameters
  • requests
  • responses
  • shared schemas
• Add examples.
• Add tags to group your endpoints in the docs (depends on: [Security Solution] Bundle root level tags  #183375)
• Make sure the generated API reference documentation looks nice and correct on bump.sh.
• Make sure the generated Serverless API reference documentation doesn't contain available only in ESS API endpoints.

Ask @maximpn to provide you with an example of a polished and documentation-ready OpenAPI spec. Please also ask @maximpn for a link to the generated API reference documentation (at the time of creating this ticket, it didn't exist).

[elasticmachine]

Pinging @elastic/security-entity-analytics (Team:Entity Analytics)

[elasticmachine]

Pinging @elastic/security-solution (Team: SecuritySolution)