Skip to content

Commit

Permalink
docs: openapi schema specifications for Projects tag (#3571)
Browse files Browse the repository at this point in the history 
<!-- Thanks for creating a PR! To make it easier for reviewers and
everyone else to understand what your changes relate to, please add some
relevant content to the headings below. Feel free to ignore or delete
sections that you don't think are relevant. Thank you! ❤️ -->

## About the changes
<!-- Describe the changes introduced. What are they and why are they
being introduced? Feel free to also add screenshots or steps to view the
changes if they're visual. -->

Improves the openapi schema specifications for the schemas belonging to
the "Projects" tag.
Expected error codes/http statues, descriptions, and example data

---------

Co-authored-by: Christopher Kolstad <chriswk@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
  • Loading branch information
@daveleek @thomasheartman
3 people committed May 19, 2023
1 parent f9409fc commit 485dab8
Show file tree
Hide file tree
Showing 15 changed files with 1,011 additions and 112 deletions.
10 changes: 0 additions & 10 deletions src/lib/openapi/meta-schema-rules.test.ts
View file
Expand Up @@ -79,8 +79,6 @@ const metaRules: Rule[] = [
},
},
knownExceptions: [
'apiTokenSchema',
'apiTokensSchema',
'batchFeaturesSchema',
'batchStaleSchema',
'changePasswordSchema',
Expand Down Expand Up @@ -115,8 +113,6 @@ const metaRules: Rule[] = [
'groupsSchema',
'groupUserModelSchema',
'healthCheckSchema',
'healthOverviewSchema',
'healthReportSchema',
'idSchema',
'instanceAdminStatsSchema',
'legalValueSchema',
Expand All @@ -132,7 +128,6 @@ const metaRules: Rule[] = [
'playgroundFeatureSchema',
'playgroundRequestSchema',
'profileSchema',
'projectEnvironmentSchema',
'projectSchema',
'projectsSchema',
'proxyClientSchema',
Expand Down Expand Up @@ -187,8 +182,6 @@ const metaRules: Rule[] = [
},
knownExceptions: [
'adminFeaturesQuerySchema',
'apiTokenSchema',
'apiTokensSchema',
'applicationSchema',
'applicationsSchema',
'batchFeaturesSchema',
Expand Down Expand Up @@ -225,8 +218,6 @@ const metaRules: Rule[] = [
'groupsSchema',
'groupUserModelSchema',
'healthCheckSchema',
'healthOverviewSchema',
'healthReportSchema',
'idSchema',
'instanceAdminStatsSchema',
'legalValueSchema',
Expand All @@ -244,7 +235,6 @@ const metaRules: Rule[] = [
'playgroundSegmentSchema',
'playgroundStrategySchema',
'profileSchema',
'projectEnvironmentSchema',
'proxyClientSchema',
'proxyFeatureSchema',
'proxyFeaturesSchema',
Expand Down
40 changes: 30 additions & 10 deletions src/lib/openapi/spec/__snapshots__/api-token-schema.test.ts.snap
View file
Expand Up @@ -6,11 +6,11 @@ exports[`apiTokenSchema empty 1`] = `
{
"instancePath": "",
"keyword": "required",
"message": "must have required property 'username'",
"message": "must have required property 'secret'",
"params": {
"missingProperty": "username",
"missingProperty": "secret",
},
"schemaPath": "#/anyOf/0/required",
"schemaPath": "#/required",
},
{
"instancePath": "",
Expand All @@ -19,21 +19,41 @@ exports[`apiTokenSchema empty 1`] = `
"params": {
"missingProperty": "tokenName",
},
"schemaPath": "#/anyOf/1/required",
"schemaPath": "#/required",
},
{
"instancePath": "",
"keyword": "anyOf",
"message": "must match a schema in anyOf",
"params": {},
"schemaPath": "#/anyOf",
"keyword": "required",
"message": "must have required property 'type'",
"params": {
"missingProperty": "type",
},
"schemaPath": "#/required",
},
{
"instancePath": "",
"keyword": "required",
"message": "must have required property 'type'",
"message": "must have required property 'project'",
"params": {
"missingProperty": "type",
"missingProperty": "project",
},
"schemaPath": "#/required",
},
{
"instancePath": "",
"keyword": "required",
"message": "must have required property 'projects'",
"params": {
"missingProperty": "projects",
},
"schemaPath": "#/required",
},
{
"instancePath": "",
"keyword": "required",
"message": "must have required property 'createdAt'",
"params": {
"missingProperty": "createdAt",
},
"schemaPath": "#/required",
},
Expand Down
1 change: 1 addition & 0 deletions src/lib/openapi/spec/api-token-schema.test.ts
View file
Expand Up @@ -5,6 +5,7 @@ import { ApiTokenSchema } from './api-token-schema';
const defaultData: ApiTokenSchema = {
secret: '',
username: '',
tokenName: '',
type: ApiTokenType.CLIENT,
environment: '',
projects: [],
Expand Down
52 changes: 32 additions & 20 deletions src/lib/openapi/spec/api-token-schema.ts
View file
Expand Up @@ -5,16 +5,28 @@ export const apiTokenSchema = {
$id: '#/components/schemas/apiTokenSchema',
type: 'object',
additionalProperties: false,
required: ['type'],
required: [
'secret',
'tokenName',
'type',
'project',
'projects',
'createdAt',
],
description:
'An overview of an [Unleash API token](https://docs.getunleash.io/reference/api-tokens-and-client-keys).',
properties: {
secret: {
type: 'string',
description: 'The token used for authentication.',
example: 'project:environment.xyzrandomstring',
},
username: {
type: 'string',
deprecated: true,
description:
'This property was deprecated in Unleash v5. Prefer the `tokenName` property instead.',
example: 'a-name',
},
tokenName: {
type: 'string',
Expand All @@ -24,57 +36,57 @@ export const apiTokenSchema = {
type: {
type: 'string',
enum: Object.values(ApiTokenType),
description: 'The type of API token',
example: 'client',
},
environment: {
type: 'string',
description:
'The environment the token has access to. `*` if it has access to all environments.',
example: 'development',
},
project: {
type: 'string',
description: 'The project this token belongs to.',
example: 'developerexperience',
},
projects: {
type: 'array',
description:
'The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as `[*]`',
items: {
type: 'string',
},
example: ['developerexperience', 'enterprisegrowth'],
},
expiresAt: {
type: 'string',
format: 'date-time',
nullable: true,
description: `The token's expiration date. NULL if the token doesn't have an expiration set.`,
example: '2023-04-19T08:15:14.000Z',
},
createdAt: {
type: 'string',
format: 'date-time',
nullable: true,
example: '2023-04-19T08:15:14.000Z',
description: 'When the token was created.',
},
seenAt: {
type: 'string',
format: 'date-time',
nullable: true,
example: '2023-04-19T08:15:14.000Z',
description:
'When the token was last seen/used to authenticate with. NULL if the token has not yet been used for authentication.',
},
alias: {
type: 'string',
nullable: true,
description: `Alias is no longer in active use and will often be NULL. It's kept around as a way of allowing old proxy tokens created with the old metadata format to keep working.`,
example: 'randomid-or-some-alias',
},
},
anyOf: [
{
properties: {
username: {
type: 'string',
},
},
required: ['username'],
},
{
properties: {
tokenName: {
type: 'string',
},
},
required: ['tokenName'],
},
],
components: {},
} as const;

Expand Down
2 changes: 2 additions & 0 deletions src/lib/openapi/spec/api-tokens-schema.ts
View file
Expand Up @@ -6,12 +6,14 @@ export const apiTokensSchema = {
type: 'object',
additionalProperties: false,
required: ['tokens'],
description: 'Contains a list of API tokens.',
properties: {
tokens: {
type: 'array',
items: {
$ref: '#/components/schemas/apiTokenSchema',
},
description: 'A list of API tokens.',
},
},
components: {
Expand Down
39 changes: 35 additions & 4 deletions src/lib/openapi/spec/health-overview-schema.ts
View file
Expand Up @@ -15,17 +15,33 @@ export const healthOverviewSchema = {
$id: '#/components/schemas/healthOverviewSchema',
type: 'object',
additionalProperties: false,
required: ['version', 'name'],
required: [
'version',
'name',
'defaultStickiness',
'mode',
'members',
'health',
'environments',
'features',
],
description: `An overview of a project's stats and its health as described in the documentation on [technical debt](https://docs.getunleash.io/reference/technical-debt)`,
properties: {
version: {
type: 'number',
type: 'integer',
description: 'The project overview version.',
example: 1,
},
name: {
type: 'string',
description: `The project's name`,
example: 'enterprisegrowth',
},
description: {
type: 'string',
nullable: true,
description: `The project's description`,
example: 'The project for all things enterprisegrowth',
},
defaultStickiness: {
type: 'string',
Expand All @@ -41,30 +57,45 @@ export const healthOverviewSchema = {
"The project's [collaboration mode](https://docs.getunleash.io/reference/project-collaboration-mode). Determines whether non-project members can submit change requests or not.",
},
members: {
type: 'number',
type: 'integer',
description: 'The number of users/members in the project.',
example: 5,
minimum: 0,
},
health: {
type: 'number',
type: 'integer',
description:
'The overall [health rating](https://docs.getunleash.io/reference/technical-debt#health-rating) of the project.',
example: 95,
},
environments: {
type: 'array',
items: {
$ref: '#/components/schemas/projectEnvironmentSchema',
},
description:
'An array containing the names of all the environments configured for the project.',
},
features: {
type: 'array',
items: {
$ref: '#/components/schemas/featureSchema',
},
description:
'An array containing an overview of all the features of the project and their individual status',
},
updatedAt: {
type: 'string',
format: 'date-time',
nullable: true,
description: 'When the project was last updated.',
example: '2023-04-19T08:15:14.000Z',
},
favorite: {
type: 'boolean',
description:
'Indicates if the project has been marked as a favorite by the current user requesting the project health overview.',
example: true,
},
stats: {
$ref: '#/components/schemas/projectStatsSchema',
Expand Down
8 changes: 8 additions & 0 deletions src/lib/openapi/spec/health-report-schema.ts
View file
Expand Up @@ -4,6 +4,8 @@ import { healthOverviewSchema } from './health-overview-schema';
export const healthReportSchema = {
...healthOverviewSchema,
$id: '#/components/schemas/healthReportSchema',
description:
'A report of the current health of the requested project, with datapoints like counters of currently active, stale, and potentially stale feature toggles.',
required: [
...healthOverviewSchema.required,
'potentiallyStaleCount',
Expand All @@ -14,12 +16,18 @@ export const healthReportSchema = {
...healthOverviewSchema.properties,
potentiallyStaleCount: {
type: 'number',
description: 'The number of potentially stale feature toggles.',
example: 5,
},
activeCount: {
type: 'number',
description: 'The number of active feature toggles.',
example: 2,
},
staleCount: {
type: 'number',
description: 'The number of stale feature toggles.',
example: 10,
},
},
} as const;
Expand Down
9 changes: 9 additions & 0 deletions src/lib/openapi/spec/project-environment-schema.ts
View file
Expand Up @@ -5,16 +5,25 @@ export const projectEnvironmentSchema = {
$id: '#/components/schemas/projectEnvironmentSchema',
type: 'object',
additionalProperties: false,
description:
'Add an environment to a project, optionally also sets if change requests are enabled for this environment on the project',
required: ['environment'],
properties: {
environment: {
type: 'string',
description: 'The environment to add to the project',
example: 'development',
},
changeRequestsEnabled: {
type: 'boolean',
description:
'Whether change requests should be enabled or for this environment on the project or not',
example: true,
},
defaultStrategy: {
$ref: '#/components/schemas/createFeatureStrategySchema',
description:
'A default strategy to create for this environment on the project.',
},
},
components: {
Expand Down

0 comments on commit 485dab8

Please sign in to comment.