[Ingest Manager]Split OpenAPI spec file into multiple files #77290
Assignees
Labels
Team:Fleet
Team label for Observability Data Collection Fleet team
Comments
|
Pinging @elastic/ingest-management (Team:Ingest Management) |
6 tasks
jfsiii
pushed a commit
that referenced
this issue
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 ├── agent_policies@delete.yaml ├── agent_policies@{agent_policy_id}.yaml ├── agent_policies@{agent_policy_id}@copy.yaml ├── agent_status.yaml ├── agents.yaml ├── agents@bulk_upgrade.yaml ├── agents@enroll.yaml ├── agents@setup.yaml ├── 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 ├── epm@categories.yaml ├── epm@packages.yaml ├── 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 issue
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 ├── agent_policies@delete.yaml ├── agent_policies@{agent_policy_id}.yaml ├── agent_policies@{agent_policy_id}@copy.yaml ├── agent_status.yaml ├── agents.yaml ├── agents@bulk_upgrade.yaml ├── agents@enroll.yaml ├── agents@setup.yaml ├── 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 ├── epm@categories.yaml ├── epm@packages.yaml ├── 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>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The current one is 4000+ lines of JSON. That makes it intimidating/challenging to edit, review, etc.
I think the strawman is a layout like
and we use
$refsto link between them. e.g. Thepathssection of the spec file wouldpaths/*look likeAnd a file at `paths/package_policies/{packagePolicyId}/post.json` like
{ "operationId": "post-agent-policy", "summary": "Agent policy - Create", "parameters": [ { "$ref": "../components/parameters/xsrfHeader.json" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "../components/schemas/NewAgentPolicy.json" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "../components/schemas/AgentPolicy.json" } } } } } } } }Everything will remain OpenAPI & JSON for now. There will be a separate ticket & pass for switching some parts to JSON schema so we can use them in more places (e.g. the route validators like #76546)
We'll also retain single bundled one e.g.
spec_bundled.jsonabove (and hopefully a simpleyarnornpxcommand to create it) any tools which don't deal with the multi-file setupThe text was updated successfully, but these errors were encountered: