Skip to content

Commit

Permalink
docs: add descriptions and examples to tag schemas (#4194)
Browse files Browse the repository at this point in the history 
## 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>
  • Loading branch information
@gastonfournier @thomasheartman
gastonfournier and thomasheartman committed Jul 11, 2023
1 parent 5c4f15e commit 58151d8
Show file tree
Hide file tree
Showing 10 changed files with 84 additions and 19 deletions.
10 changes: 0 additions & 10 deletions src/lib/openapi/meta-schema-rules.test.ts
View file
Expand Up @@ -117,17 +117,12 @@ const metaRules: Rule[] = [
'splashSchema',
'stateSchema',
'strategiesSchema',
'tagTypeSchema',
'tagTypesSchema',
'tagWithVersionSchema',
'uiConfigSchema',
'updateFeatureSchema',
'updateTagTypeSchema',
'upsertContextFieldSchema',
'upsertStrategySchema',
'usersGroupsBaseSchema',
'validateEdgeTokensSchema',
'validateTagTypeSchema',
'variantFlagSchema',
'versionSchema',
'projectOverviewSchema',
Expand Down Expand Up @@ -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',
Expand Down
7 changes: 7 additions & 0 deletions src/lib/openapi/spec/tag-type-schema.ts
View file
Expand Up @@ -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: {},
Expand Down
6 changes: 6 additions & 0 deletions src/lib/openapi/spec/tag-types-schema.ts
View file
Expand Up @@ -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',
},
Expand Down
4 changes: 4 additions & 0 deletions src/lib/openapi/spec/tag-with-version-schema.ts
View file
Expand Up @@ -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',
Expand Down
5 changes: 5 additions & 0 deletions src/lib/openapi/spec/update-tag-type-schema.ts
View file
Expand Up @@ -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: {},
Expand Down
3 changes: 3 additions & 0 deletions src/lib/openapi/spec/validate-tag-type-schema.ts
View file
Expand Up @@ -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',
Expand Down
30 changes: 28 additions & 2 deletions src/lib/routes/admin-api/tag-type.ts
View file
Expand Up @@ -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;

Expand Down Expand Up @@ -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),
},
}),
],
});
Expand All @@ -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'),
}),
Expand All @@ -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'),
}),
Expand All @@ -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),
},
}),
],
Expand All @@ -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'),
}),
Expand All @@ -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),
},
}),
],
Expand Down
26 changes: 24 additions & 2 deletions src/lib/routes/admin-api/tag.ts
View file
Expand Up @@ -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';

Expand Down Expand Up @@ -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),
},
}),
],
});
Expand All @@ -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'),
}),
Expand All @@ -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),
},
}),
],
Expand All @@ -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),
},
}),
],
Expand All @@ -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,
},
Expand Down
2 changes: 1 addition & 1 deletion src/lib/services/addon-service.ts
View file
Expand Up @@ -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,
Expand Down
10 changes: 6 additions & 4 deletions src/lib/services/tag-type-service.ts
View file
Expand Up @@ -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,
Expand All @@ -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(
Expand All @@ -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> {
Expand Down

0 comments on commit 58151d8

Please sign in to comment.