[Security Solution] Sort root level tags alphabetically by name in the result bundle#189482
Merged
maximpn merged 3 commits intoelastic:mainfrom Aug 1, 2024
Merged
[Security Solution] Sort root level tags alphabetically by name in the result bundle#189482maximpn merged 3 commits intoelastic:mainfrom
maximpn merged 3 commits intoelastic:mainfrom
Conversation
maximpn
added
release_note:skip
Contributor
|
Pinging @elastic/security-detections-response (Team:Detections and Resp) |
Contributor
|
Pinging @elastic/security-solution (Team: SecuritySolution) |
Contributor
|
Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management) |
Contributor
Author
|
/ci |
💚 Build Succeeded
Metrics [docs]
History
To update your PR or re-run it, just comment with: cc @maximpn |
lcawl
pushed a commit
to lcawl/kibana
that referenced
this pull request
Aug 20, 2024
…e result bundle (elastic#189482) **Resolves:** elastic#189463 ## Summary This PR adds functionality to produce result bundle with by default sorted root level OpenAPI `tags` alphabetically by name as requested by the Docs Engineering team. ## Details Bump.sh (new API reference documentation platform) uses OpenAPI tags for grouping API endpoints together. It displays tags encountered order which isn't always a desired one. To streamline displaying tags we need them sorted alphabetically by name. ## Screenshots **Example API reference documentation page BEFORE**  **Example API reference documentation page AFTER** 
lcawl
added a commit
that referenced
this pull request
Aug 20, 2024
…189262) (#190541) # Backport This will backport the bundler aspects of the following commits from `main` to `8.15`: - [[HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262)](#189262) - #189621 - #189482 - #189348 - #189472 - #188110 - #188812 <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Maxim Palenov","email":"maxim.palenov@elastic.co"},"sourceCommit":{"committedDate":"2024-08-13T10:45:35Z","message":"[HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262)\n\n**Addresses:** https://github.com/elastic/kibana/issues/186356\r\n**Relates to:** https://github.com/elastic/kibana/issues/184428\r\n\r\n## Summary\r\n\r\nThis PR adds a merging JS script based on the utility implemented in #186356. Resulted OpenAPI bundle as committed in `oas_docs/output/kibana.serverless.bundled.yaml`.\r\n\r\n## Details\r\n\r\nhttps://github.com//pull/188110 implements and exposes `merge` utility design to merge source OpenAPI specs without processing. It's has only a programmatic API. To merge OpenAPI specs it's required to add a JS script like below\r\n\r\n```js\r\nconst { merge } = require('@kbn/openapi-bundler');\r\n\r\n(async () => {\r\n await merge({\r\n sourceGlobs: [/* a list of source globs goes here */],\r\n outputFilePath: 'path/to/the/output/file.yaml',\r\n });\r\n})();\r\n```\r\n\r\nThe JS script added in this PR includes source OpenAPI specs presented in `oas_docs/makefile` plus Security Solution OpenAPI specs based on https://github.com/elastic/kibana/issues/184428.\r\n\r\n**To run** the script use the following command from Kibana root folder\r\n\r\n```bash\r\nnode ./oas_docs/scripts/merge_serverless_oas.js \r\n```\r\n\r\n## Known linting issues with Security Solution OpenAPI specs\r\n\r\nRunning Spectral OpenAPI linter on the result bundle shows a number of errors caused by `no-$ref-siblings` rule. This caused by the current code generator implementation which requires `default` property to be set next to `$ref` though it's not correct for OpenAPI `3.0.3` while it's allowed in `3.1`. It seems that Bump.sh handles such cases properly though by properly showing a default value.\r\n\r\nWe need to analyze the problem and decide if/when we should fix it.\r\n\r\nThe rest of warnings look fixable and will be addressed in the next stage after setting up linter rules.\r\n\r\n## Next steps\r\n\r\nSince `@kbn/openapi-bundler` package is tailored specifically for Kibana it should replace Redocly currently used to merge OpenAPI specs. It also means `oas_docs/makefile` should be superseded by JS script(s) using `merge` utility form `@kbn/openapi-bundler` package.\r\n\r\n`@kbn/openapi-bundler` SHOULD NOT replace OpenAPI linters since it doesn't perform thorough linting. It's good if we continue adopting `spectral-cli` for linting purposes.","sha":"7a2e7bef9644eaf04fd820d16b8ee137b3c00f2b","branchLabelMapping":{"^v8.16.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Core","release_note:skip","backport:skip","docs","Team: SecuritySolution","Feature:OAS","v8.16.0"],"number":189262,"url":"https://github.com/elastic/kibana/pull/189262","mergeCommit":{"message":"[HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262)\n\n**Addresses:** https://github.com/elastic/kibana/issues/186356\r\n**Relates to:** https://github.com/elastic/kibana/issues/184428\r\n\r\n## Summary\r\n\r\nThis PR adds a merging JS script based on the utility implemented in #186356. Resulted OpenAPI bundle as committed in `oas_docs/output/kibana.serverless.bundled.yaml`.\r\n\r\n## Details\r\n\r\nhttps://github.com//pull/188110 implements and exposes `merge` utility design to merge source OpenAPI specs without processing. It's has only a programmatic API. To merge OpenAPI specs it's required to add a JS script like below\r\n\r\n```js\r\nconst { merge } = require('@kbn/openapi-bundler');\r\n\r\n(async () => {\r\n await merge({\r\n sourceGlobs: [/* a list of source globs goes here */],\r\n outputFilePath: 'path/to/the/output/file.yaml',\r\n });\r\n})();\r\n```\r\n\r\nThe JS script added in this PR includes source OpenAPI specs presented in `oas_docs/makefile` plus Security Solution OpenAPI specs based on https://github.com/elastic/kibana/issues/184428.\r\n\r\n**To run** the script use the following command from Kibana root folder\r\n\r\n```bash\r\nnode ./oas_docs/scripts/merge_serverless_oas.js \r\n```\r\n\r\n## Known linting issues with Security Solution OpenAPI specs\r\n\r\nRunning Spectral OpenAPI linter on the result bundle shows a number of errors caused by `no-$ref-siblings` rule. This caused by the current code generator implementation which requires `default` property to be set next to `$ref` though it's not correct for OpenAPI `3.0.3` while it's allowed in `3.1`. It seems that Bump.sh handles such cases properly though by properly showing a default value.\r\n\r\nWe need to analyze the problem and decide if/when we should fix it.\r\n\r\nThe rest of warnings look fixable and will be addressed in the next stage after setting up linter rules.\r\n\r\n## Next steps\r\n\r\nSince `@kbn/openapi-bundler` package is tailored specifically for Kibana it should replace Redocly currently used to merge OpenAPI specs. It also means `oas_docs/makefile` should be superseded by JS script(s) using `merge` utility form `@kbn/openapi-bundler` package.\r\n\r\n`@kbn/openapi-bundler` SHOULD NOT replace OpenAPI linters since it doesn't perform thorough linting. It's good if we continue adopting `spectral-cli` for linting purposes.","sha":"7a2e7bef9644eaf04fd820d16b8ee137b3c00f2b"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.16.0","labelRegex":"^v8.16.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/189262","number":189262,"mergeCommit":{"message":"[HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262)\n\n**Addresses:** https://github.com/elastic/kibana/issues/186356\r\n**Relates to:** https://github.com/elastic/kibana/issues/184428\r\n\r\n## Summary\r\n\r\nThis PR adds a merging JS script based on the utility implemented in #186356. Resulted OpenAPI bundle as committed in `oas_docs/output/kibana.serverless.bundled.yaml`.\r\n\r\n## Details\r\n\r\nhttps://github.com//pull/188110 implements and exposes `merge` utility design to merge source OpenAPI specs without processing. It's has only a programmatic API. To merge OpenAPI specs it's required to add a JS script like below\r\n\r\n```js\r\nconst { merge } = require('@kbn/openapi-bundler');\r\n\r\n(async () => {\r\n await merge({\r\n sourceGlobs: [/* a list of source globs goes here */],\r\n outputFilePath: 'path/to/the/output/file.yaml',\r\n });\r\n})();\r\n```\r\n\r\nThe JS script added in this PR includes source OpenAPI specs presented in `oas_docs/makefile` plus Security Solution OpenAPI specs based on https://github.com/elastic/kibana/issues/184428.\r\n\r\n**To run** the script use the following command from Kibana root folder\r\n\r\n```bash\r\nnode ./oas_docs/scripts/merge_serverless_oas.js \r\n```\r\n\r\n## Known linting issues with Security Solution OpenAPI specs\r\n\r\nRunning Spectral OpenAPI linter on the result bundle shows a number of errors caused by `no-$ref-siblings` rule. This caused by the current code generator implementation which requires `default` property to be set next to `$ref` though it's not correct for OpenAPI `3.0.3` while it's allowed in `3.1`. It seems that Bump.sh handles such cases properly though by properly showing a default value.\r\n\r\nWe need to analyze the problem and decide if/when we should fix it.\r\n\r\nThe rest of warnings look fixable and will be addressed in the next stage after setting up linter rules.\r\n\r\n## Next steps\r\n\r\nSince `@kbn/openapi-bundler` package is tailored specifically for Kibana it should replace Redocly currently used to merge OpenAPI specs. It also means `oas_docs/makefile` should be superseded by JS script(s) using `merge` utility form `@kbn/openapi-bundler` package.\r\n\r\n`@kbn/openapi-bundler` SHOULD NOT replace OpenAPI linters since it doesn't perform thorough linting. It's good if we continue adopting `spectral-cli` for linting purposes.","sha":"7a2e7bef9644eaf04fd820d16b8ee137b3c00f2b"}}]}] BACKPORT--> --------- Co-authored-by: Maxim Palenov <maxim.palenov@elastic.co>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 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.
Resolves: #189463
Summary
This PR adds functionality to produce result bundle with by default sorted root level OpenAPI
tagsalphabetically by name as requested by the Docs Engineering team.Details
Bump.sh (new API reference documentation platform) uses OpenAPI tags for grouping API endpoints together. It displays tags encountered order which isn't always a desired one. To streamline displaying tags we need them sorted alphabetically by name.
Screenshots
Example API reference documentation page BEFORE
Example API reference documentation page AFTER
