[SecuritySolution][Detections] Update Create Rule API docs

[spong]

Our API docs are manually maintained and so need love as we continue to add features. With all the recent changes around indicator match and threshold rules for 7.12, let's review and make updates as needed. Thanks for raising this @jmikell821! 🙂

While our talks to streamline API doc generation (#81964 / #82587) appear to have stalled, we can at least streamline this process to keep things easier on all of us and allow more time for the @elastic/security-docs folks to focus on content. 🙌

The Create Rule Docs covers the API for creating a single rule, and the requirements around all the different rule types. Bulk operations have dedicated documentation.

The rules schema can be found referenced in the body validation of the create_rules_route, and is made up of commonParams across all rule types, and typeSpecificParams for each individual rule type.

Note: The below is relevant as of 7.11, but is really only to tie these docs to source to streamline this process while we work towards generating docs.

cc @madirey @rylnd @FrankHassanabad

Common Params (source)

const commonParams = {
  required: {
    name,
    description,
    risk_score,
    severity,
  },
  optional: {
    building_block_type,
    note,
    license,
    output_index,
    timeline_id,
    timeline_title,
    meta,
    rule_name_override,
    timestamp_override,
  },
  defaultable: {
    tags,
    interval,
    enabled,
    throttle: throttleOrNull,
    actions,
    author,
    false_positives,
    from,
    rule_id,
    // maxSignals not used in ML rules but probably should be used
    max_signals,
    risk_score_mapping,
    severity_mapping,
    threat: threats,
    to,
    references,
    version,
    exceptions_list: listArray,
  },
};

eqlCreateParams (source)

const eqlRuleParams = {
  required: {
    type: t.literal('eql'),
    language: t.literal('eql'),
    query,
  },
  optional: {
    index,
    filters,
    event_category_override,
  },
  defaultable: {},
};

threatMatchCreateParams (source)

const threatMatchRuleParams = {
  required: {
    type: t.literal('threat_match'),
    query,
    threat_query,
    threat_mapping,
    threat_index,
  },
  optional: {
    index,
    filters,
    saved_id,
    threat_filters,
    threat_indicator_path,
    threat_language: t.keyof({ kuery: null, lucene: null }),
    concurrent_searches,
    items_per_search,
  },
  defaultable: {
    language: t.keyof({ kuery: null, lucene: null }),
  },
};

queryCreateParams (source)

const queryRuleParams = {
  required: {
    type: t.literal('query'),
  },
  optional: {
    index,
    filters,
    saved_id,
  },
  defaultable: {
    query,
    language: t.keyof({ kuery: null, lucene: null }),
  },
};

savedQueryCreateParams (source)

const savedQueryRuleParams = {
  required: {
    type: t.literal('saved_query'),
    saved_id,
  },
  optional: {
    // Having language, query, and filters possibly defined adds more code confusion and probably user confusion
    // if the saved object gets deleted for some reason
    index,
    query,
    filters,
  },
  defaultable: {
    language: t.keyof({ kuery: null, lucene: null }),
  },
};

thresholdCreateParams (source)

const thresholdRuleParams = {
  required: {
    type: t.literal('threshold'),
    query,
    threshold,
  },
  optional: {
    index,
    filters,
    saved_id,
  },
  defaultable: {
    language: t.keyof({ kuery: null, lucene: null }),
  },
};

machineLearningCreateParams (source)

const machineLearningRuleParams = {
  required: {
    type: t.literal('machine_learning'),
    anomaly_threshold,
    machine_learning_job_id,
  },
  optional: {},
  defaultable: {},
};

[elasticmachine]

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