Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
1 of 31 tasks
maximpn opened this issue May 17, 2024 · 6 comments
Open
1 of 31 tasks

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

maximpn opened this issue May 17, 2024 · 6 comments
Labels
docs Team:Detection Engine Security Solution Detection Engine Area Team:Detection Rule Management Security Detection Rule Management Team Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc.

Comments

@maximpn
Copy link
Contributor

maximpn commented May 17, 2024 •
edited

Epic: https://github.com/elastic/security-team/issues/9398
Depends on: #183661, #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.
  • 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).
@maximpn maximpn added docs Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. Team:Detection Rule Management Security Detection Rule Management Team Project:Serverless Work as part of the Serverless project for its initial release Team:Detection Engine Security Solution Detection Engine Area labels May 17, 2024
@elasticmachine
Copy link
Contributor

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

@elasticmachine
Copy link
Contributor

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

@elasticmachine
Copy link
Contributor

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

@elasticmachine
Copy link
Contributor

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

@banderror banderror changed the title [Security Solution] Make existing OpenAPI specs for Detection Engine API documentation-ready [Security Solution] Make existing OpenAPI specs for Detections API documentation-ready May 17, 2024
@banderror banderror removed the Project:Serverless Work as part of the Serverless project for its initial release label Jun 4, 2024
@maximpn maximpn mentioned this issue Jun 7, 2024
Merged
Merged
@natasha-moore-elastic
Copy link
Contributor

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: #187224.

@banderror
Copy link
Contributor

@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.

natasha-moore-elastic added a commit that referenced this issue Jul 18, 2024
@natasha-moore-elastic @kibanamachine
[DOCS] Improves Detections API docs content (#187224)
ac5beb6 
## Summary

Resolves elastic/docs-projects#219 by
improving the Detections API docs content. Adds missing and improves
existing operation summaries and operation descriptions.

Also addresses some of the work planned in
#183702.

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
@maximpn maximpn mentioned this issue Aug 7, 2024
Open
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Team:Detection Engine Security Solution Detection Engine Area Team:Detection Rule Management Security Detection Rule Management Team Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@maximpn @banderror @elasticmachine @natasha-moore-elastic