Skip to content

Commit

Permalink
docs: Auth tag (#4126)
Browse files Browse the repository at this point in the history 
## What
This adds openapi documentation for the Auth tagged operations and
connected schemas.

## Discussion points
Our user schema seems to be exposing quite a bit of internal fields, I
flagged the isApi field as deprecated, I can imagine quite a few of
these fields also being deprecated to prepare for removal in next major
version, but I was unsure which ones were safe to do so with.

## Observation
We have some technical debt around the shape of the schema we're
claiming we're returning and what we actually are returning. I believe
@gastonfournier also observed this when we turned on validation for our
endpoints.

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
  • Loading branch information
@thomasheartman
Christopher Kolstad and thomasheartman committed Jul 4, 2023
1 parent 95a0215 commit 0b18491
Show file tree
Hide file tree
Showing 13 changed files with 518 additions and 37 deletions.
14 changes: 0 additions & 14 deletions src/lib/openapi/meta-schema-rules.test.ts
View file
Expand Up @@ -92,13 +92,11 @@ const metaRules: Rule[] = [
knownExceptions: [
'batchFeaturesSchema',
'batchStaleSchema',
'changePasswordSchema',
'cloneFeatureSchema',
'createApiTokenSchema',
'createFeatureSchema',
'createInvitedUserSchema',
'createUserSchema',
'emailSchema',
'environmentsSchema',
'environmentsProjectSchema',
'eventSchema',
Expand All @@ -118,7 +116,6 @@ const metaRules: Rule[] = [
'groupsSchema',
'groupUserModelSchema',
'idSchema',
'loginSchema',
'maintenanceSchema',
'toggleMaintenanceSchema',
'meSchema',
Expand All @@ -135,7 +132,6 @@ const metaRules: Rule[] = [
'pushVariantsSchema',
'resetPasswordSchema',
'requestsPerSecondSchema',
'roleSchema',
'sdkContextSchema',
'searchEventsSchema',
'setUiConfigSchema',
Expand All @@ -145,7 +141,6 @@ const metaRules: Rule[] = [
'tagTypeSchema',
'tagTypesSchema',
'tagWithVersionSchema',
'tokenUserSchema',
'uiConfigSchema',
'updateApiTokenSchema',
'updateFeatureSchema',
Expand All @@ -154,11 +149,9 @@ const metaRules: Rule[] = [
'updateUserSchema',
'upsertContextFieldSchema',
'upsertStrategySchema',
'userSchema',
'usersGroupsBaseSchema',
'usersSchema',
'validateEdgeTokensSchema',
'validatePasswordSchema',
'validateTagTypeSchema',
'variantFlagSchema',
'versionSchema',
Expand All @@ -183,15 +176,13 @@ const metaRules: Rule[] = [
'applicationsSchema',
'batchFeaturesSchema',
'batchStaleSchema',
'changePasswordSchema',
'cloneFeatureSchema',
'createApiTokenSchema',
'createFeatureSchema',
'createFeatureStrategySchema',
'createInvitedUserSchema',
'createUserSchema',
'dateSchema',
'emailSchema',
'environmentsSchema',
'eventSchema',
'eventsSchema',
Expand All @@ -209,7 +200,6 @@ const metaRules: Rule[] = [
'groupsSchema',
'groupUserModelSchema',
'idSchema',
'loginSchema',
'maintenanceSchema',
'toggleMaintenanceSchema',
'meSchema',
Expand All @@ -229,7 +219,6 @@ const metaRules: Rule[] = [
'resetPasswordSchema',
'requestsPerSecondSchema',
'requestsPerSecondSegmentedSchema',
'roleSchema',
'setStrategySortOrderSchema',
'setUiConfigSchema',
'sortOrderSchema',
Expand All @@ -238,7 +227,6 @@ const metaRules: Rule[] = [
'tagTypeSchema',
'tagTypesSchema',
'tagWithVersionSchema',
'tokenUserSchema',
'uiConfigSchema',
'updateApiTokenSchema',
'updateFeatureSchema',
Expand All @@ -247,12 +235,10 @@ const metaRules: Rule[] = [
'updateUserSchema',
'upsertContextFieldSchema',
'upsertStrategySchema',
'userSchema',
'usersGroupsBaseSchema',
'usersSchema',
'usersSearchSchema',
'validateEdgeTokensSchema',
'validatePasswordSchema',
'validateTagTypeSchema',
'variantFlagSchema',
'variantsSchema',
Expand Down
7 changes: 7 additions & 0 deletions src/lib/openapi/spec/change-password-schema.ts
View file
Expand Up @@ -5,12 +5,19 @@ export const changePasswordSchema = {
type: 'object',
additionalProperties: false,
required: ['token', 'password'],
description: 'Change password as long as the token is a valid token',
properties: {
token: {
description:
'A reset token used to validate that the user is allowed to change the password.',
type: 'string',
example:
'$2a$15$QzeW/y5/MEppCWVEkoX5euejobYOLSd4We21LQjjKlWH9l2I3wCke',
},
password: {
type: 'string',
description: 'The new password for the user',
example: 'correct horse battery staple',
},
},
components: {},
Expand Down
4 changes: 4 additions & 0 deletions src/lib/openapi/spec/email-schema.ts
View file
Expand Up @@ -5,9 +5,13 @@ export const emailSchema = {
type: 'object',
additionalProperties: false,
required: ['email'],
description:
'Represents the email of a user. Used to send email communication (reset password, welcome mail etc)',
properties: {
email: {
description: 'The email address',
type: 'string',
example: 'test@example.com',
},
},
components: {},
Expand Down
5 changes: 5 additions & 0 deletions src/lib/openapi/spec/login-schema.ts
View file
Expand Up @@ -5,12 +5,17 @@ export const loginSchema = {
type: 'object',
additionalProperties: false,
required: ['username', 'password'],
description: 'A username/password login request',
properties: {
username: {
description: 'The username trying to log in',
type: 'string',
example: 'user',
},
password: {
description: 'The password of the user trying to log in',
type: 'string',
example: 'hunter2',
},
},
components: {},
Expand Down
14 changes: 13 additions & 1 deletion src/lib/openapi/spec/role-schema.ts
View file
Expand Up @@ -3,20 +3,32 @@ import { FromSchema } from 'json-schema-to-ts';
export const roleSchema = {
$id: '#/components/schemas/roleSchema',
type: 'object',
description:
'A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform',
additionalProperties: false,
required: ['id', 'type', 'name'],
properties: {
id: {
type: 'number',
type: 'integer',
description: 'The role id',
example: 9,
minimum: 0,
},
type: {
description:
'A role can either be a global role (applies to all projects) or a project role',
type: 'string',
example: 'global',
},
name: {
description: `The name of the role`,
type: 'string',
example: 'Editor',
},
description: {
description: `A more detailed description of the role and what use it's intended for`,
type: 'string',
example: `Users with the editor role have access to most features in Unleash but can not manage users and roles in the global scope. Editors will be added as project owners when creating projects and get superuser rights within the context of these projects. Users with the editor role will also get access to most permissions on the default project by default.`,
},
},
components: {},
Expand Down
14 changes: 13 additions & 1 deletion src/lib/openapi/spec/token-user-schema.ts
View file
Expand Up @@ -5,23 +5,35 @@ export const tokenUserSchema = {
$id: '#/components/schemas/tokenUserSchema',
type: 'object',
additionalProperties: false,
description: 'A user identified by a token',
required: ['id', 'name', 'email', 'token', 'createdBy', 'role'],
properties: {
id: {
type: 'number',
type: 'integer',
description: 'The user id',
example: 7,
},
name: {
description: 'The name of the user',
type: 'string',
example: 'Test McTest',
},
email: {
description: 'The email of the user',
type: 'string',
example: 'test@example.com',
},
token: {
description: 'A token uniquely identifying a user',
type: 'string',
example: 'user:xyzrandomstring',
},
createdBy: {
description:
'A username or email identifying which user created this token',
type: 'string',
nullable: true,
example: 'admin@example.com',
},
role: {
$ref: '#/components/schemas/roleSchema',
Expand Down
40 changes: 37 additions & 3 deletions src/lib/openapi/spec/user-schema.ts
View file
Expand Up @@ -5,50 +5,84 @@ export const userSchema = {
$id: '#/components/schemas/userSchema',
type: 'object',
additionalProperties: false,
description: 'An Unleash user',
required: ['id'],
properties: {
id: {
type: 'number',
description: 'The user id',
type: 'integer',
minimum: 0,
example: 123,
},
isAPI: {
description:
'(Deprecated): Used internally to know which operations the user should be allowed to perform',
type: 'boolean',
example: true,
deprecated: true,
},
name: {
description: 'Name of the user',
type: 'string',
example: 'User',
},
email: {
description: 'Email of the user',
type: 'string',
example: 'user@example.com',
},
username: {
description: 'A unique username for the user',
type: 'string',
example: 'hunter',
},
imageUrl: {
description: `URL used for the userprofile image`,
type: 'string',
example: 'https://example.com/242x200.png',
},
inviteLink: {
description: `If the user is actively inviting other users, this is the link that can be shared with other users`,
type: 'string',
example: 'http://localhost:4242/invite-link/some-secret',
},
loginAttempts: {
type: 'number',
description:
'How many unsuccessful attempts at logging in has the user made',
type: 'integer',
minimum: 0,
example: 3,
},
emailSent: {
description: 'Is the welcome email sent to the user or not',
type: 'boolean',
example: false,
},
rootRole: {
type: 'number',
description:
'Which [root role](https://docs.getunleash.io/reference/rbac#standard-roles) this user is assigned',
type: 'integer',
example: 1,
minimum: 0,
},
seenAt: {
description: 'The last time this user logged in',
type: 'string',
format: 'date-time',
nullable: true,
example: '2023-06-30T11:42:00.345Z',
},
createdAt: {
description: 'The user was created at this time',
type: 'string',
format: 'date-time',
example: '2023-06-30T11:41:00.123Z',
},
accountType: {
description: 'A user is either an actual User or a Service Account',
type: 'string',
enum: AccountTypes,
example: 'User',
},
},
components: {},
Expand Down
4 changes: 4 additions & 0 deletions src/lib/openapi/spec/validate-password-schema.ts
View file
Expand Up @@ -5,9 +5,13 @@ export const validatePasswordSchema = {
type: 'object',
additionalProperties: false,
required: ['password'],
description:
'Used to validate passwords obeying [Unleash password guidelines](https://docs.getunleash.io/reference/deploy/securing-unleash#password-requirements)',
properties: {
password: {
description: 'The password to validate',
type: 'string',
example: 'hunter2',
},
},
components: {},
Expand Down

0 comments on commit 0b18491

Please sign in to comment.