[Security Solution] Improve OpenAPI specs for Detections API

[maximpn]

Epic: https://github.com/elastic/kibana/issues/200310

Summary

We need to make our API reference docs for Detections API more user-friendly and usable. For that, we need to improve and polish the corresponding OpenAPI specs: enrich them with summaries, descriptions, examples of usage, etc:

• Add summaries for:
  • API endpoints
  • HTTP methods
• Add descriptions for:
  • API endpoints
  • HTTP methods
  • endpoint's parameters
  • requests
  • responses
  • shared schemas
• Add examples of usage of each API endpoint.
• Make sure the generated API reference documentation looks nice and correct on bump.sh.

API endpoints

The following public API endpoints are available in both Serverless and ESS:

• [ ] GET /api/detection_engine/rules
• [ ] POST /api/detection_engine/rules
• [ ] PUT /api/detection_engine/rules
• [ ] PATCH /api/detection_engine/rules
• [ ] DELETE /api/detection_engine/rules
• [ ] POST /api/detection_engine/rules/_bulk_action
• [ ] POST /api/detection_engine/rules/_export
• [ ] POST /api/detection_engine/rules/_import
• [ ] GET /api/detection_engine/rules/_find
• [ ] GET /api/detection_engine/tags
• [ ] GET /api/detection_engine/rules/prepackaged/_status
• [ ] PUT /api/detection_engine/rules/prepackaged
• [ ] POST /api/detection_engine/rules/preview
• [ ] POST /api/detection_engine/signals/status
• [ ] POST /api/detection_engine/signals/tags
• [ ] POST /api/detection_engine/signals/search
• [ ] POST /api/detection_engine/signals/assignees
• [ ] GET /api/detection_engine/privileges
• [ ] POST /api/detection_engine/rules/{id}/exceptions

The following public API endpoints are available in ESS only:

• [ ] POST /api/detection_engine/rules/_bulk_create
• [ ] PUT /api/detection_engine/rules/_bulk_update
• [ ] PATCH /api/detection_engine/rules/_bulk_update
• [ ] DELETE /api/detection_engine/rules/_bulk_delete
• [ ] POST /api/detection_engine/rules/_bulk_delete
• [ ] GET /api/detection_engine/signals/migration_status
• [ ] POST /api/detection_engine/signals/migration
• [ ] POST /api/detection_engine/signals/finalize_migration
• [ ] POST /api/detection_engine/index
• [ ] GET /api/detection_engine/index
• [ ] DELETE /api/detection_engine/index

[elasticmachine]

Pinging @elastic/security-detections-response (Team:Detections and Resp)

[elasticmachine]

Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management)

[elasticmachine]

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

[elasticmachine]

Pinging @elastic/security-detection-engine (Team:Detection Engine)

[natasha-moore-elastic]

Hi @banderror & @maximpn, as part of a Docs OnWeek project, I made some editorial suggestions to the Detections API specs, mostly adding missing operation summaries and descriptions, or making changes to existing ones to align with our guidelines. Letting you know as this partially addresses some of the work planned in this issue. Here's the related PR: https://github.com/elastic/kibana/pull/187224.

[banderror]

@natasha-moore-elastic Thanks for this contribution, I might be able to take a quick look this week, and @maximpn will review the PR in detail when he's back from PTO.