Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Security Solution] Sort root level tags alphabetically by name in the result bundle #189482

Merged
merged 3 commits into from
Aug 1, 2024

Conversation

maximpn
Copy link
Contributor

@maximpn maximpn commented Jul 30, 2024

Resolves: #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
image

Example API reference documentation page AFTER
image

@maximpn maximpn added release_note:skip Skip the PR/issue when compiling release notes docs Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. Team:Detection Rule Management Security Detection Rule Management Team v8.16.0 labels Jul 30, 2024
@maximpn maximpn self-assigned this Jul 30, 2024
@maximpn maximpn marked this pull request as ready for review July 31, 2024 11:58
@maximpn maximpn requested a review from a team as a code owner July 31, 2024 11:58
@maximpn maximpn requested a review from xcrzx July 31, 2024 11:58
@elasticmachine
Copy link
Contributor

Pinging @elastic/security-detections-response (Team:Detections and Resp)

@elasticmachine
Copy link
Contributor

Pinging @elastic/security-solution (Team: SecuritySolution)

@elasticmachine
Copy link
Contributor

Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management)

@maximpn
Copy link
Contributor Author

maximpn commented Jul 31, 2024

/ci

@kibana-ci
Copy link
Collaborator

💚 Build Succeeded

Metrics [docs]

✅ unchanged

History

  • 💛 Build #224595 was flaky cb59269c8ab18ad68e8582c71be11411157f1f89

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

cc @maximpn

Copy link
Contributor

@xcrzx xcrzx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@maximpn maximpn merged commit 9b009e0 into elastic:main Aug 1, 2024
19 checks passed
@kibanamachine kibanamachine added the backport:skip This commit does not require backporting label Aug 1, 2024
@maximpn maximpn deleted the sort-tags-oas branch August 1, 2024 12:13
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**
![image](https://github.com/user-attachments/assets/f66f0488-2a94-4e40-be91-808782b489b2)

**Example API reference documentation page AFTER**
![image](https://github.com/user-attachments/assets/24ef9844-3d9d-4309-a1f0-69a2a9a23f08)
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":"[email protected]"},"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 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
backport:skip This commit does not require backporting docs release_note:skip Skip the PR/issue when compiling release notes Team:Detection Rule Management Security Detection Rule Management Team Team:Detections and Resp Security Detection Response Team Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. v8.16.0
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants