Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
## 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. <details><summary>how these were generated (requires node 12+)</summary> ``` nvm use 12; npx @redocly/openapi-cli bundle entrypoint.yaml -o bundled.json npx @redocly/openapi-cli bundle entrypoint.yaml -o bundled.yaml ``` </details> <details><summary>How to generate with node 10+</summary> ``` npx swagger-cli bundle -o bundled.json -t json entrypoint.yaml npx swagger-cli bundle -o bundled.yaml -t yaml entrypoint.yaml ``` </details> * [Paths](paths/README.md): Started with a flat `paths` directory with each path in a separate file. We can move on to a nested file-per-operation like #77378 or any other approach later <details><summary><code>tree ./paths</code></summary> ``` 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 ``` </details> * [Components](components/README.md): Reusable components like [`schemas`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject), [`responses`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject) [`parameters`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject), etc <details><summary><code>tree ./components</code></summary> ``` 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 ``` </details>
- Loading branch information