Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-03-27 00:19:39 +01:00
Code Issues Projects Releases Wiki Activity

docs: add descriptions and examples to tag schemas (#4194)

Browse Source 
## About the changes
- Adding descriptions and examples to tag and tag types schemas
- Adding standard errors, summaries, and descriptions to tag and tag
types endpoints
- Some improvements on compilation errors

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
This commit is contained in:
Gastón Fournier 2023-07-11 10:02:00 +02:00 committed by GitHub
parent 5c4f15ea5d
commit 58151d8d80
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 84 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/lib/openapi/meta-schema-rules.test.ts
View File

@ -117,17 +117,12 @@ const metaRules: Rule[] = [
'splashSchema',
'stateSchema',
'strategiesSchema',
'tagTypeSchema',
'tagTypesSchema',
'tagWithVersionSchema',
'uiConfigSchema',
'updateFeatureSchema',
'updateTagTypeSchema',
'upsertContextFieldSchema',
'upsertStrategySchema',
'usersGroupsBaseSchema',
'validateEdgeTokensSchema',
'validateTagTypeSchema',
'variantFlagSchema',
'versionSchema',
'projectOverviewSchema',
@ -173,18 +168,13 @@ const metaRules: Rule[] = [
'sortOrderSchema',
'splashSchema',
'strategiesSchema',
'tagTypeSchema',
'tagTypesSchema',
'tagWithVersionSchema',
'uiConfigSchema',
'updateFeatureSchema',
'updateTagTypeSchema',
'upsertContextFieldSchema',
'upsertStrategySchema',
'usersGroupsBaseSchema',
'usersSearchSchema',
'validateEdgeTokensSchema',
'validateTagTypeSchema',
'variantFlagSchema',
'variantsSchema',
'versionSchema',

7
src/lib/openapi/spec/tag-type-schema.ts
View File

@ -4,17 +4,24 @@ export const tagTypeSchema = {
$id: '#/components/schemas/tagTypeSchema',
type: 'object',
additionalProperties: false,
description: 'A tag type.',
required: ['name'],
properties: {
name: {
type: 'string',
description: 'The name of the tag type.',
example: 'color',
},
description: {
type: 'string',
description: 'The description of the tag type.',
example: 'A tag type for describing the color of a tag.',
},
icon: {
type: 'string',
nullable: true,
description: 'The icon of the tag type.',
example: 'not-really-used',
},
},
components: {},

6
src/lib/openapi/spec/tag-types-schema.ts
View File

@ -6,12 +6,18 @@ export const tagTypesSchema = {
type: 'object',
additionalProperties: false,
required: ['version', 'tagTypes'],
description:
'A list of tag types with a version number representing the schema used to model the tag types.',
properties: {
version: {
type: 'integer',
description:
'The version of the schema used to model the tag types.',
example: 1,
},
tagTypes: {
type: 'array',
description: 'The list of tag types.',
items: {
$ref: '#/components/schemas/tagTypeSchema',
},

4
src/lib/openapi/spec/tag-with-version-schema.ts
View File

@ -6,9 +6,13 @@ export const tagWithVersionSchema = {
type: 'object',
additionalProperties: false,
required: ['version', 'tag'],
description:
'A tag with a version number representing the schema used to model the tag.',
properties: {
version: {
type: 'integer',
description: 'The version of the schema used to model the tag.',
example: 1,
},
tag: {
$ref: '#/components/schemas/tagSchema',

5
src/lib/openapi/spec/update-tag-type-schema.ts
View File

@ -3,12 +3,17 @@ import { FromSchema } from 'json-schema-to-ts';
export const updateTagTypeSchema = {
$id: '#/components/schemas/updateTagTypeSchema',
type: 'object',
description: 'The request body for updating a tag type.',
properties: {
description: {
type: 'string',
description: 'The description of the tag type.',
example: 'A tag type for describing the color of a tag.',
},
icon: {
type: 'string',
description: 'The icon of the tag type.',
example: 'not-really-used',
},
},
components: {},

3
src/lib/openapi/spec/validate-tag-type-schema.ts
View File

@ -5,9 +5,12 @@ export const validateTagTypeSchema = {
$id: '#/components/schemas/validateTagTypeSchema',
type: 'object',
required: ['valid', 'tagType'],
description: 'The result of validating a tag type.',
properties: {
valid: {
type: 'boolean',
description: 'Whether or not the tag type is valid.',
example: true,
},
tagType: {
$ref: '#/components/schemas/tagTypeSchema',

30
src/lib/routes/admin-api/tag-type.ts
View File

@ -25,7 +25,10 @@ import {
} from '../../openapi/spec/tag-type-schema';
import { UpdateTagTypeSchema } from '../../openapi/spec/update-tag-type-schema';
import { OpenApiService } from '../../services/openapi-service';
import { emptyResponse } from '../../openapi/util/standard-responses';
import {
emptyResponse,
getStandardResponses,
} from '../../openapi/util/standard-responses';
const version = 1;
@ -56,7 +59,12 @@ class TagTypeController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'getTagTypes',
responses: { 200: createResponseSchema('tagTypesSchema') },
summary: 'Get all tag types',
description: 'Get a list of all available tag types.',
responses: {
200: createResponseSchema('tagTypesSchema'),
...getStandardResponses(401, 403),
},
}),
],
});
@ -69,8 +77,11 @@ class TagTypeController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'createTagType',
summary: 'Create a tag type',
description: 'Create a new tag type.',
responses: {
201: resourceCreatedResponseSchema('tagTypeSchema'),
...getStandardResponses(400, 401, 403, 409, 415),
},
requestBody: createRequestSchema('tagTypeSchema'),
}),
@ -85,8 +96,12 @@ class TagTypeController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'validateTagType',
summary: 'Validate a tag type',
description:
'Validates whether if the body of the request is a valid tag and whether the a tag type with that name already exists or not. If a tag type with the same name exists, this operation will return a 409 status code.',
responses: {
200: createResponseSchema('validateTagTypeSchema'),
...getStandardResponses(400, 401, 403, 409, 415),
},
requestBody: createRequestSchema('tagTypeSchema'),
}),
@ -101,8 +116,11 @@ class TagTypeController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'getTagType',
summary: 'Get a tag type',
description: 'Get a tag type by name.',
responses: {
200: createResponseSchema('tagTypeSchema'),
...getStandardResponses(401, 403),
},
}),
],
@ -116,8 +134,12 @@ class TagTypeController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'updateTagType',
summary: 'Update a tag type',
description:
'Update the configuration for the specified tag type.',
responses: {
200: emptyResponse,
...getStandardResponses(400, 401, 403, 415),
},
requestBody: createRequestSchema('updateTagTypeSchema'),
}),
@ -133,8 +155,12 @@ class TagTypeController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'deleteTagType',
summary: 'Delete a tag type',
description:
'Deletes a tag type. If any features have tags of this type, those tags will be deleted.',
responses: {
200: emptyResponse,
...getStandardResponses(401, 403),
},
}),
],

26
src/lib/routes/admin-api/tag.ts
View File

@ -21,7 +21,10 @@ import {
tagWithVersionSchema,
TagWithVersionSchema,
} from '../../openapi/spec/tag-with-version-schema';
import { emptyResponse } from '../../openapi/util/standard-responses';
import {
emptyResponse,
getStandardResponses,
} from '../../openapi/util/standard-responses';
import FeatureTagService from 'lib/services/feature-tag-service';
import { IFlagResolver } from '../../types';
@ -65,7 +68,12 @@ class TagController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'getTags',
responses: { 200: createResponseSchema('tagsSchema') },
summary: 'List all tags.',
description: 'List all tags available in Unleash.',
responses: {
200: createResponseSchema('tagsSchema'),
...getStandardResponses(401, 403),
},
}),
],
});
@ -78,10 +86,13 @@ class TagController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'createTag',
summary: 'Create a new tag.',
description: 'Create a new tag with the specified data.',
responses: {
201: resourceCreatedResponseSchema(
'tagWithVersionSchema',
),
...getStandardResponses(400, 401, 403, 409, 415),
},
requestBody: createRequestSchema('tagSchema'),
}),
@ -97,8 +108,12 @@ class TagController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'getTagsByType',
summary: 'List all tags of a given type.',
description:
'List all tags of a given type. If the tag type does not exist it returns an empty list.',
responses: {
200: createResponseSchema('tagsSchema'),
...getStandardResponses(401, 403),
},
}),
],
@ -112,8 +127,12 @@ class TagController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'getTag',
summary: 'Get a tag by type and value.',
description:
'Get a tag by type and value. Can be used to check whether a given tag already exists in Unleash or not.',
responses: {
200: createResponseSchema('tagWithVersionSchema'),
...getStandardResponses(401, 403, 404),
},
}),
],
@ -128,6 +147,9 @@ class TagController extends Controller {
openApiService.validPath({
tags: ['Tags'],
operationId: 'deleteTag',
summary: 'Delete a tag.',
description:
'Delete a tag by type and value. When a tag is deleted all references to the tag are removed.',
responses: {
200: emptyResponse,
},

2
src/lib/services/addon-service.ts
View File

@ -170,7 +170,7 @@ export default class AddonService {
const tagTypes = provider.definition.tagTypes || [];
const createTags = tagTypes.map(async (tagType) => {
try {
await this.tagTypeService.validateUnique(tagType);
await this.tagTypeService.validateUnique(tagType.name);
await this.tagTypeService.createTagType(
tagType,
providerName,

10
src/lib/services/tag-type-service.ts
View File

@ -48,7 +48,7 @@ export default class TagTypeService {
const data = (await tagTypeSchema.validateAsync(
newTagType,
)) as ITagType;
await this.validateUnique(data);
await this.validateUnique(data.name);
await this.tagTypeStore.createTagType(data);
await this.eventStore.store({
type: TAG_TYPE_CREATED,
@ -58,7 +58,7 @@ export default class TagTypeService {
return data;
}
async validateUnique({ name }: Pick<ITagType, 'name'>): Promise<boolean> {
async validateUnique(name: string): Promise<boolean> {
const exists = await this.tagTypeStore.exists(name);
if (exists) {
throw new NameExistsError(
@ -68,9 +68,11 @@ export default class TagTypeService {
return Promise.resolve(true);
}
async validate(tagType: ITagType): Promise<void> {
async validate(tagType: Partial<ITagType> | undefined): Promise<void> {
await tagTypeSchema.validateAsync(tagType);
await this.validateUnique(tagType);
if (tagType && tagType.name) {
await this.validateUnique(tagType.name);
}
}
async deleteTagType(name: string, userName: string): Promise<void> {