From de8e9a03aeb344defa047c6fc2d3d4a9c5093d04 Mon Sep 17 00:00:00 2001 From: Tymoteusz Czech <2625371+Tymek@users.noreply.github.com> Date: Wed, 5 Jul 2023 11:25:58 +0200 Subject: [PATCH] Inline endpoint descriptions (#4145) Update OpenApi docs --- .../export-import-controller.ts | 11 +++-- src/lib/features/playground/playground.ts | 11 +++-- src/lib/openapi/endpoint-descriptions.ts | 40 ------------------- src/lib/routes/admin-api/event.ts | 12 ++++-- 4 files changed, 23 insertions(+), 51 deletions(-) delete mode 100644 src/lib/openapi/endpoint-descriptions.ts diff --git a/src/lib/features/export-import-toggles/export-import-controller.ts b/src/lib/features/export-import-toggles/export-import-controller.ts index 12a267c263..7a75645e0c 100644 --- a/src/lib/features/export-import-toggles/export-import-controller.ts +++ b/src/lib/features/export-import-toggles/export-import-controller.ts @@ -24,7 +24,6 @@ import { IAuthRequest } from '../../routes/unleash-types'; import { extractUsername } from '../../util'; import { BadDataError, InvalidOperationError } from '../../error'; import ApiUser from '../../types/api-user'; -import { endpointDescriptions } from '../../openapi/endpoint-descriptions'; class ExportImportController extends Controller { private logger: Logger; @@ -74,7 +73,9 @@ class ExportImportController extends Controller { 200: createResponseSchema('exportResultSchema'), ...getStandardResponses(404), }, - ...endpointDescriptions.admin.export, + description: + "Exports all features listed in the `features` property from the environment specified in the request body. If set to `true`, the `downloadFile` property will let you download a file with the exported data. Otherwise, the export data is returned directly as JSON. Refer to the documentation for more information about [Unleash's export functionality](https://docs.getunleash.io/reference/deploy/environment-import-export#export).", + summary: 'Export feature toggles from an environment', }), ], }); @@ -94,7 +95,8 @@ class ExportImportController extends Controller { ), ...getStandardResponses(404), }, - ...endpointDescriptions.admin.validateImport, + summary: 'Validate feature import data', + description: `Validates a feature toggle data set. Checks whether the data can be imported into the specified project and environment. The returned value is an object that contains errors, warnings, and permissions required to perform the import, as described in the [import documentation](https://docs.getunleash.io/reference/deploy/environment-import-export#import).`, }), ], }); @@ -112,7 +114,8 @@ class ExportImportController extends Controller { 200: emptyResponse, ...getStandardResponses(404), }, - ...endpointDescriptions.admin.import, + summary: 'Import feature toggles', + description: `[Import feature toggles](https://docs.getunleash.io/reference/deploy/environment-import-export#import) into a specific project and environment.`, }), ], }); diff --git a/src/lib/features/playground/playground.ts b/src/lib/features/playground/playground.ts index 564c76f96d..a4d3d25996 100644 --- a/src/lib/features/playground/playground.ts +++ b/src/lib/features/playground/playground.ts @@ -5,7 +5,6 @@ import { NONE } from '../../types/permissions'; import Controller from '../../routes/controller'; import { OpenApiService } from '../../services/openapi-service'; import { createResponseSchema } from '../../openapi/util/create-response-schema'; -import { endpointDescriptions } from '../../openapi/endpoint-descriptions'; import { getStandardResponses } from '../../openapi/util/standard-responses'; import { createRequestSchema } from '../../openapi/util/create-request-schema'; import { @@ -55,7 +54,10 @@ export default class PlaygroundController extends Controller { 200: createResponseSchema('playgroundResponseSchema'), }, requestBody: createRequestSchema('playgroundRequestSchema'), - ...endpointDescriptions.admin.playground, + description: + 'Use the provided `context`, `environment`, and `projects` to evaluate toggles on this Unleash instance. Returns a list of all toggles that match the parameters and what they evaluate to. The response also contains the input parameters that were provided.', + summary: + 'Evaluate an Unleash context against a set of environments and projects.', }), ], }); @@ -78,7 +80,10 @@ export default class PlaygroundController extends Controller { requestBody: createRequestSchema( 'advancedPlaygroundRequestSchema', ), - ...endpointDescriptions.admin.advancedPlayground, + description: + 'Use the provided `context`, `environments`, and `projects` to evaluate toggles on this Unleash instance. You can use comma-separated values to provide multiple values to each context field. Returns a combinatorial list of all toggles that match the parameters and what they evaluate to. The response also contains the input parameters that were provided.', + summary: + 'Batch evaluate an Unleash context against a set of environments and projects.', }), ], }); diff --git a/src/lib/openapi/endpoint-descriptions.ts b/src/lib/openapi/endpoint-descriptions.ts deleted file mode 100644 index 6d12d03da1..0000000000 --- a/src/lib/openapi/endpoint-descriptions.ts +++ /dev/null @@ -1,40 +0,0 @@ -export const endpointDescriptions = { - admin: { - events: { - description: - 'Returns **the last 100** events from the Unleash instance when called without a query parameter. When called with a `project` parameter, returns **all events** for the specified project.\n\nIf the provided project does not exist, the list of events will be empty.', - summary: - 'Get the most recent events from the Unleash instance or all events related to a project.', - }, - eventsPerFeature: { - description: - 'Returns all events related to the specified feature toggle. If the feature toggle does not exist, the list of events will be empty.', - summary: 'Get all events related to a specific feature toggle.', - }, - playground: { - description: - 'Use the provided `context`, `environment`, and `projects` to evaluate toggles on this Unleash instance. Returns a list of all toggles that match the parameters and what they evaluate to. The response also contains the input parameters that were provided.', - summary: - 'Evaluate an Unleash context against a set of environments and projects.', - }, - advancedPlayground: { - description: - 'Use the provided `context`, `environments`, and `projects` to evaluate toggles on this Unleash instance. You can use comma-separated values to provide multiple values to each context field. Returns a combinatorial list of all toggles that match the parameters and what they evaluate to. The response also contains the input parameters that were provided.', - summary: - 'Batch evaluate an Unleash context against a set of environments and projects.', - }, - export: { - description: - "Exports all features listed in the `features` property from the environment specified in the request body. If set to `true`, the `downloadFile` property will let you download a file with the exported data. Otherwise, the export data is returned directly as JSON. Refer to the documentation for more information about [Unleash's export functionality](https://docs.getunleash.io/reference/deploy/environment-import-export#export).", - summary: 'Export feature toggles from an environment', - }, - validateImport: { - summary: 'Validate feature import data', - description: `Validates a feature toggle data set. Checks whether the data can be imported into the specified project and environment. The returned value is an object that contains errors, warnings, and permissions required to perform the import, as described in the [import documentation](https://docs.getunleash.io/reference/deploy/environment-import-export#import).`, - }, - import: { - summary: 'Import feature toggles', - description: `[Import feature toggles](https://docs.getunleash.io/reference/deploy/environment-import-export#import) into a specific project and environment.`, - }, - }, -} as const; diff --git a/src/lib/routes/admin-api/event.ts b/src/lib/routes/admin-api/event.ts index e6b3bc0427..dd54bbaa06 100644 --- a/src/lib/routes/admin-api/event.ts +++ b/src/lib/routes/admin-api/event.ts @@ -8,7 +8,6 @@ import Controller from '../controller'; import { anonymiseKeys } from '../../util/anonymise'; import { OpenApiService } from '../../services/openapi-service'; import { createResponseSchema } from '../../openapi/util/create-response-schema'; -import { endpointDescriptions } from '../../openapi/endpoint-descriptions'; import { eventsSchema, EventsSchema, @@ -67,8 +66,10 @@ export default class EventController extends Controller { in: 'query', }, ], - - ...endpointDescriptions.admin.events, + description: + 'Returns **the last 100** events from the Unleash instance when called without a query parameter. When called with a `project` parameter, returns **all events** for the specified project.\n\nIf the provided project does not exist, the list of events will be empty.', + summary: + 'Get the most recent events from the Unleash instance or all events related to a project.', }), ], }); @@ -86,7 +87,10 @@ export default class EventController extends Controller { ...getStandardResponses(401), 200: createResponseSchema('featureEventsSchema'), }, - ...endpointDescriptions.admin.eventsPerFeature, + description: + 'Returns all events related to the specified feature toggle. If the feature toggle does not exist, the list of events will be empty.', + summary: + 'Get all events related to a specific feature toggle.', }), ], });