From 9b009e0f292975065132f4014e03e18185cb5cc8 Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Thu, 1 Aug 2024 14:13:25 +0200 Subject: [PATCH] [Security Solution] Sort root level tags alphabetically by name in the result bundle (#189482) **Resolves:** https://github.com/elastic/kibana/issues/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) --- .../src/bundler/merge_documents/merge_tags.ts | 10 ++- .../result_overrides/sort_tags.test.ts | 63 +++++++++++++++++++ .../tests/create_oas_document.ts | 5 ++ .../merger/result_overrides/sort_tags.test.ts | 63 +++++++++++++++++++ 4 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 packages/kbn-openapi-bundler/tests/bundler/result_overrides/sort_tags.test.ts create mode 100644 packages/kbn-openapi-bundler/tests/merger/result_overrides/sort_tags.test.ts diff --git a/packages/kbn-openapi-bundler/src/bundler/merge_documents/merge_tags.ts b/packages/kbn-openapi-bundler/src/bundler/merge_documents/merge_tags.ts index e1b8411538deb..3eeb555359df3 100644 --- a/packages/kbn-openapi-bundler/src/bundler/merge_documents/merge_tags.ts +++ b/packages/kbn-openapi-bundler/src/bundler/merge_documents/merge_tags.ts @@ -19,5 +19,13 @@ export function mergeTags( const merged = mergeArrays(tagsArrayOfArrays); - return merged.length > 0 ? merged : undefined; + if (merged.length === 0) { + return; + } + + // To streamline API endpoints categorization it's expected that + // tags are sorted alphabetically by name + merged.sort((a, b) => a.name.localeCompare(b.name)); + + return merged; } diff --git a/packages/kbn-openapi-bundler/tests/bundler/result_overrides/sort_tags.test.ts b/packages/kbn-openapi-bundler/tests/bundler/result_overrides/sort_tags.test.ts new file mode 100644 index 0000000000000..0e4a8e77e576b --- /dev/null +++ b/packages/kbn-openapi-bundler/tests/bundler/result_overrides/sort_tags.test.ts @@ -0,0 +1,63 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import { bundleSpecs } from '../bundle_specs'; +import { createOASDocument } from '../../create_oas_document'; + +describe('OpenAPI Bundler - sort tags', () => { + it('sorts tags in the result bundle', async () => { + const spec1 = createOASDocument({ + paths: { + '/api/some_api': { + get: { + responses: {}, + }, + }, + }, + tags: [ + { name: 'Some tag name', description: 'Some description' }, + { name: '1 tag', description: 'Some description' }, + ], + }); + const spec2 = createOASDocument({ + paths: { + '/api/some_api': { + post: { + responses: {}, + }, + }, + }, + tags: [{ name: 'Another tag name', description: 'Another description' }], + }); + const spec3 = createOASDocument({ + paths: { + '/api/some_api': { + put: { + responses: {}, + }, + }, + }, + tags: [{ name: 'Spec3 tag name', description: 'Spec3 tag description' }], + }); + + const [bundledSpec] = Object.values( + await bundleSpecs({ + 1: spec1, + 2: spec2, + 3: spec3, + }) + ); + + expect(bundledSpec.tags).toEqual([ + { name: '1 tag', description: 'Some description' }, + { name: 'Another tag name', description: 'Another description' }, + { name: 'Some tag name', description: 'Some description' }, + { name: 'Spec3 tag name', description: 'Spec3 tag description' }, + ]); + }); +}); diff --git a/packages/kbn-openapi-bundler/tests/create_oas_document.ts b/packages/kbn-openapi-bundler/tests/create_oas_document.ts index a16cef4119f03..2ce877ebe3524 100644 --- a/packages/kbn-openapi-bundler/tests/create_oas_document.ts +++ b/packages/kbn-openapi-bundler/tests/create_oas_document.ts @@ -15,6 +15,7 @@ export function createOASDocument(overrides: { components?: OpenAPIV3.ComponentsObject; servers?: OpenAPIV3.ServerObject[]; security?: OpenAPIV3.SecurityRequirementObject[]; + tags?: OpenAPIV3.TagObject[]; }): OpenAPIV3.Document { const document: OpenAPIV3.Document = { openapi: overrides.openapi ?? '3.0.3', @@ -39,5 +40,9 @@ export function createOASDocument(overrides: { document.security = overrides.security; } + if (overrides.tags) { + document.tags = overrides.tags; + } + return document; } diff --git a/packages/kbn-openapi-bundler/tests/merger/result_overrides/sort_tags.test.ts b/packages/kbn-openapi-bundler/tests/merger/result_overrides/sort_tags.test.ts new file mode 100644 index 0000000000000..1fa25fe59ecf1 --- /dev/null +++ b/packages/kbn-openapi-bundler/tests/merger/result_overrides/sort_tags.test.ts @@ -0,0 +1,63 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0 and the Server Side Public License, v 1; you may not use this file except + * in compliance with, at your election, the Elastic License 2.0 or the Server + * Side Public License, v 1. + */ + +import { mergeSpecs } from '../merge_specs'; +import { createOASDocument } from '../../create_oas_document'; + +describe('OpenAPI Merger - sort tags', () => { + it('sorts tags in the result bundle', async () => { + const spec1 = createOASDocument({ + paths: { + '/api/some_api': { + get: { + responses: {}, + }, + }, + }, + tags: [ + { name: 'Some tag name', description: 'Some description' }, + { name: '1 tag', description: 'Some description' }, + ], + }); + const spec2 = createOASDocument({ + paths: { + '/api/some_api': { + post: { + responses: {}, + }, + }, + }, + tags: [{ name: 'Another tag name', description: 'Another description' }], + }); + const spec3 = createOASDocument({ + paths: { + '/api/some_api': { + put: { + responses: {}, + }, + }, + }, + tags: [{ name: 'Spec3 tag name', description: 'Spec3 tag description' }], + }); + + const [mergedSpec] = Object.values( + await mergeSpecs({ + 1: spec1, + 2: spec2, + 3: spec3, + }) + ); + + expect(mergedSpec.tags).toEqual([ + { name: '1 tag', description: 'Some description' }, + { name: 'Another tag name', description: 'Another description' }, + { name: 'Some tag name', description: 'Some description' }, + { name: 'Spec3 tag name', description: 'Spec3 tag description' }, + ]); + }); +});