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

[maximpn]

Epic: https://github.com/elastic/security-team/issues/9398 Depends on: https://github.com/elastic/kibana/issues/183661, https://github.com/elastic/kibana/issues/183701

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 Detections 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 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

To do

For all the Detections 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.
• [x] Add tags to group your endpoints in the docs (depends on: https://github.com/elastic/kibana/issues/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-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.