[Ingest Manager] Split OpenAPI spec into multiple files #77378
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jfsiii
added
the
Team:Fleet
Contributor
Author
|
@elasticmachine merge upstream |
Contributor
💚 Build SucceededBuild metricsdistributable file count
History
To update your PR or re-run it, just comment with: |
jfsiii
pushed a commit
that referenced
this pull request
Oct 13, 2020
## 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>
jfsiii
pushed a commit
that referenced
this pull request
Oct 13, 2020
## 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>
Contributor
Author
|
was replaced by #80107 |
Contributor
Author
|
was replaced by #80107 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
WIP. First pass at #77290
spec_entry.jsonis the version which links to the various files on disk.spec_bundled.jsonis the resolved output of that entry & other files in one file. It's currently generated withnpx swagger-cli bundle spec_entry.json -o spec_bundled.jsonPaths: this defines each endpoint. A path can have one operation per http method.
Went with "directory-per-path" approach which is largely "Each operation in a separate file" from paths/README.md. Only
index.jsonat the moment but they can be split out to something likeget.json,put.jsonorsome-operation-id.json, have a localexamples, etc.tree ./pathsComponents: Reusable components like
schemas,responsesparameters, etctree ./componentsChecklist
Delete any items that are not applicable to this PR.