[Ingest Manager] Split up OpenAPI spec file

[jfsiii]

Summary

replaces #77378
fixes #77290

• Replace the 4000+ line spec_oas3.json file with one ~75 line overview file entrypoint.yaml which imports the various pieces from other directories.
• Switched from JSON to YAML for "source" files because they're less noisy & more human-friendly. package-registry & package-spec both define specs in YAML as well. We can always convert them to JS for any library that needs it.

Dev docs

New structure

openapi/
├── README.md
├── bundled.json
├── bundled.yaml
├── components/
├── entrypoint.yaml
└── paths/

There are README.md files in openapi, openapi/components, & openapi/paths with information about the purpose, conventions, decisions, etc for that directory

• entrypoint.yaml is the overview file which links to the various files on disk.

• bundled.{yaml,json} is the resolved output of that entry & other files in a single file.

  how these were generated (requires node 12+)

  nvm use 12;
  npx @redocly/openapi-cli bundle entrypoint.yaml -o bundled.json
  npx @redocly/openapi-cli bundle entrypoint.yaml -o bundled.yaml
  

  How to generate with node 10+

  npx swagger-cli bundle -o bundled.json -t json entrypoint.yaml
  npx swagger-cli bundle -o bundled.yaml -t yaml entrypoint.yaml
  

• Paths: Started with a flat paths directory with each path in a separate file. We can move on to a nested file-per-operation like [Ingest Manager] Split OpenAPI spec into multiple files #77378 or any other approach later

  tree ./paths

  paths/
  ├── README.md
  ├── agent_policies.yaml
  ├── [email protected]
  ├── agent_policies@{agent_policy_id}.yaml
  ├── agent_policies@{agent_policy_id}@copy.yaml
  ├── agent_status.yaml
  ├── agents.yaml
  ├── agents@bulk_upgrade.yaml
  ├── [email protected]
  ├── [email protected]
  ├── agents@{agent_id}.yaml
  ├── agents@{agent_id}@acks.yaml
  ├── agents@{agent_id}@checkin.yaml
  ├── agents@{agent_id}@events.yaml
  ├── agents@{agent_id}@unenroll.yaml
  ├── agents@{agent_id}@upgrade.yaml
  ├── enrollment_api_keys.yaml
  ├── enrollment_api_keys@{key_id}.yaml
  ├── [email protected]
  ├── [email protected]
  ├── epm@packages@{pkgkey}.yaml
  ├── install@{os_type}.yaml
  ├── package_policies.yaml
  ├── package_policies@{package_policy_id}.yaml
  └── setup.yaml
  

• Components: Reusable components like schemas, responses parameters, etc

  tree ./components

  components/
  ├── README.md
  ├── callbacks
  ├── examples
  ├── headers
  │   └── kbn_xsrf.yaml
  ├── links
  ├── parameters
  │   ├── kuery.yaml
  │   ├── page_index.yaml
  │   └── page_size.yaml
  ├── request_bodies
  ├── responses
  ├── schemas
  │   ├── access_api_key.yaml
  │   ├── agent.yaml
  │   ├── agent_event.yaml
  │   ├── agent_metadata.yaml
  │   ├── agent_policy.yaml
  │   ├── agent_status.yaml
  │   ├── agent_type.yaml
  │   ├── bulk_upgrade_agents.yaml
  │   ├── enrollment_api_key.yaml
  │   ├── new_agent_event.yaml
  │   ├── new_agent_policy.yaml
  │   ├── new_package_policy.yaml
  │   ├── package_info.yaml
  │   ├── package_policy.yaml
  │   ├── search_result.yaml
  │   └── upgrade_agent.yaml
  └── security_schemes
  

[elasticmachine]

Pinging @elastic/ingest-management (Team:Ingest Management)

[jfsiii]

cc @EricDavisX There's still an easy-to-paste single file at bundled.json

but now there's also a way to link to a more focused spec file like agents@{agent_id}@checkin.yaml

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: 236e326

Metrics [docs]

distributable file count

id	before	after	diff
default	48447	48493	+46

History

• 💚 Build #81031 succeeded dff3067
• 💚 Build #80965 succeeded 4f77965
• 💔 Build #80963 failed ed3e554

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

[EricDavisX]

this is super cool John - nice work.

[skh]

This is much easier to comprehend now, great change! 👍

[ph]

@jfsiii does this include the added bulk action endpoint and upgrade changes?

[jfsiii]

@ph no, this was merely breaking up the file. Missing endpoints and other issues are tracked in #79574