diff --git a/src/lib/openapi/meta-schema-rules.test.ts b/src/lib/openapi/meta-schema-rules.test.ts index a1e9a06c98..92a207d61c 100644 --- a/src/lib/openapi/meta-schema-rules.test.ts +++ b/src/lib/openapi/meta-schema-rules.test.ts @@ -147,9 +147,6 @@ const metaRules: Rule[] = [ 'proxyClientSchema', 'proxyFeatureSchema', 'proxyFeaturesSchema', - 'publicSignupTokenSchema', - 'publicSignupTokensSchema', - 'publicSignupTokenUpdateSchema', 'pushVariantsSchema', 'resetPasswordSchema', 'requestsPerSecondSchema', @@ -265,10 +262,6 @@ const metaRules: Rule[] = [ 'proxyClientSchema', 'proxyFeatureSchema', 'proxyFeaturesSchema', - 'publicSignupTokenCreateSchema', - 'publicSignupTokenSchema', - 'publicSignupTokensSchema', - 'publicSignupTokenUpdateSchema', 'pushVariantsSchema', 'resetPasswordSchema', 'requestsPerSecondSchema', diff --git a/src/lib/openapi/spec/public-signup-token-create-schema.ts b/src/lib/openapi/spec/public-signup-token-create-schema.ts index 1a4194b044..5502b2a8d2 100644 --- a/src/lib/openapi/spec/public-signup-token-create-schema.ts +++ b/src/lib/openapi/spec/public-signup-token-create-schema.ts @@ -3,6 +3,8 @@ import { FromSchema } from 'json-schema-to-ts'; export const publicSignupTokenCreateSchema = { $id: '#/components/schemas/publicSignupTokenCreateSchema', type: 'object', + description: + 'Used for creating a [public invite link](https://docs.getunleash.io/reference/public-signup#public-sign-up-tokens)', additionalProperties: false, required: ['name', 'expiresAt'], properties: { diff --git a/src/lib/openapi/spec/public-signup-token-schema.ts b/src/lib/openapi/spec/public-signup-token-schema.ts index b4f592d3d4..1561d276a3 100644 --- a/src/lib/openapi/spec/public-signup-token-schema.ts +++ b/src/lib/openapi/spec/public-signup-token-schema.ts @@ -4,6 +4,8 @@ import { roleSchema } from './role-schema'; export const publicSignupTokenSchema = { $id: '#/components/schemas/publicSignupTokenSchema', + description: + 'Used for transporting a [public invite link](https://docs.getunleash.io/reference/public-signup#public-sign-up-tokens)', type: 'object', additionalProperties: false, required: [ @@ -18,28 +20,44 @@ export const publicSignupTokenSchema = { ], properties: { secret: { + description: + 'The actual value of the token. This is the part that is used by Unleash to create an invite link', type: 'string', + example: 'a3c84b25409ea8ca1782ef17f94a42fc', }, url: { description: 'The public signup link for the token. Users who follow this link will be taken to a signup page where they can create an Unleash user.', type: 'string', + example: + 'https://sandbox.getunleash.io/enterprise/new-user?invite=a3c84b25409ea8ca1782ef17f94a42fc', }, name: { + description: "The token's name. Only for displaying in the UI", type: 'string', + example: 'Invite public viewers', }, enabled: { + description: + 'Whether the token is active. This property will always be `false` for a token that has expired.', type: 'boolean', + example: true, }, expiresAt: { type: 'string', + description: 'The time when the token will expire.', format: 'date-time', + example: '2023-04-12T11:13:31.960Z', }, createdAt: { type: 'string', format: 'date-time', + description: 'When the token was created.', + example: '2023-04-12T11:13:31.960Z', }, createdBy: { + description: "The creator's email or username", + example: 'someone@example.com', type: 'string', nullable: true, }, diff --git a/src/lib/openapi/spec/public-signup-token-update-schema.ts b/src/lib/openapi/spec/public-signup-token-update-schema.ts index 8170eaa28e..aca51253c3 100644 --- a/src/lib/openapi/spec/public-signup-token-update-schema.ts +++ b/src/lib/openapi/spec/public-signup-token-update-schema.ts @@ -2,6 +2,8 @@ import { FromSchema } from 'json-schema-to-ts'; export const publicSignupTokenUpdateSchema = { $id: '#/components/schemas/publicSignupTokenUpdateSchema', + description: + "Used by Unleash for updating a token's expiration date or, when deleting the invite link, it's status", type: 'object', additionalProperties: false, properties: { @@ -9,9 +11,12 @@ export const publicSignupTokenUpdateSchema = { type: 'string', description: `The token's expiration date.`, format: 'date-time', + example: '2023-04-11T15:46:56Z', }, enabled: { + description: `Whether the token is active or not.`, type: 'boolean', + example: true, }, }, components: {}, diff --git a/src/lib/openapi/spec/public-signup-tokens-schema.ts b/src/lib/openapi/spec/public-signup-tokens-schema.ts index 14a940b460..bfb8d366a1 100644 --- a/src/lib/openapi/spec/public-signup-tokens-schema.ts +++ b/src/lib/openapi/spec/public-signup-tokens-schema.ts @@ -6,11 +6,30 @@ import { publicSignupTokenSchema } from './public-signup-token-schema'; export const publicSignupTokensSchema = { $id: '#/components/schemas/publicSignupTokensSchema', type: 'object', + description: 'A wrapper object containing all the public signup tokens', additionalProperties: false, required: ['tokens'], properties: { tokens: { type: 'array', + description: 'An array of all the public signup tokens', + example: [ + { + secret: 'a3c84b25409ea8ca1782ef17f94a42fc', + url: 'https://my_unleash_instance/new-user?invite=a3c84b25409ea8ca1782ef17f94a42fc', + name: 'Invite public viewers', + enabled: false, + expiresAt: '2023-04-12T11:13:31.960Z', + createdAt: '2023-04-12T11:13:31.960Z', + createdBy: 'someone', + users: null, + role: { + id: 3, + type: 'root', + name: 'Viewer', + }, + }, + ], items: { $ref: '#/components/schemas/publicSignupTokenSchema', }, diff --git a/src/lib/routes/admin-api/public-signup.ts b/src/lib/routes/admin-api/public-signup.ts index dec59b6782..a7c2381e9c 100644 --- a/src/lib/routes/admin-api/public-signup.ts +++ b/src/lib/routes/admin-api/public-signup.ts @@ -1,31 +1,33 @@ import { Response } from 'express'; import Controller from '../controller'; -import { ADMIN } from '../../types/permissions'; +import { + ADMIN, + IUnleashConfig, + IUnleashServices, + serializeDates, +} from '../../types'; import { Logger } from '../../logger'; -import { AccessService } from '../../services/access-service'; +import { + AccessService, + OpenApiService, + PublicSignupTokenService, +} from '../../services'; import { IAuthRequest } from '../unleash-types'; -import { IUnleashConfig, IUnleashServices } from '../../types'; -import { OpenApiService } from '../../services/openapi-service'; -import { createRequestSchema } from '../../openapi/util/create-request-schema'; import { + createRequestSchema, createResponseSchema, - resourceCreatedResponseSchema, -} from '../../openapi/util/create-response-schema'; -import { serializeDates } from '../../types/serialize-dates'; -import { PublicSignupTokenService } from '../../services/public-signup-token-service'; -import UserService from '../../services/user-service'; -import { + getStandardResponses, + PublicSignupTokenCreateSchema, publicSignupTokenSchema, PublicSignupTokenSchema, -} from '../../openapi/spec/public-signup-token-schema'; -import { publicSignupTokensSchema, PublicSignupTokensSchema, -} from '../../openapi/spec/public-signup-tokens-schema'; -import { PublicSignupTokenCreateSchema } from '../../openapi/spec/public-signup-token-create-schema'; -import { PublicSignupTokenUpdateSchema } from '../../openapi/spec/public-signup-token-update-schema'; -import { extractUsername } from '../../util/extract-user'; + PublicSignupTokenUpdateSchema, + resourceCreatedResponseSchema, +} from '../../openapi'; +import UserService from '../../services/user-service'; +import { extractUsername } from '../../util'; interface TokenParam { token: string; @@ -91,6 +93,8 @@ export class PublicSignupController extends Controller { tags: ['Public signup tokens'], operationId: 'createPublicSignupToken', summary: 'Create a public signup token', + description: + 'Lets administrators create a invite link to share with colleagues. People that join using the public invite are assigned the `Viewer` role', requestBody: createRequestSchema( 'publicSignupTokenCreateSchema', ), @@ -98,6 +102,7 @@ export class PublicSignupController extends Controller { 201: resourceCreatedResponseSchema( 'publicSignupTokenSchema', ), + ...getStandardResponses(400, 401, 403), }, }), ], @@ -117,6 +122,7 @@ export class PublicSignupController extends Controller { operationId: 'getPublicSignupToken', responses: { 200: createResponseSchema('publicSignupTokenSchema'), + ...getStandardResponses(401, 403), }, }), ], @@ -132,11 +138,15 @@ export class PublicSignupController extends Controller { tags: ['Public signup tokens'], operationId: 'updatePublicSignupToken', summary: 'Update a public signup token', + description: + "Update information about a specific token. The `:token` part of the URL should be the token's secret.", + requestBody: createRequestSchema( 'publicSignupTokenUpdateSchema', ), responses: { 200: createResponseSchema('publicSignupTokenSchema'), + ...getStandardResponses(400, 401, 403), }, }), ], diff --git a/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap b/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap index b7fe378627..40a8dac25a 100644 --- a/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap +++ b/src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap @@ -3735,6 +3735,7 @@ Stats are divided into current and previous **windows**. }, "publicSignupTokenCreateSchema": { "additionalProperties": false, + "description": "Used for creating a [public invite link](https://docs.getunleash.io/reference/public-signup#public-sign-up-tokens)", "properties": { "expiresAt": { "description": "The token's expiration date.", @@ -3754,23 +3755,34 @@ Stats are divided into current and previous **windows**. }, "publicSignupTokenSchema": { "additionalProperties": false, + "description": "Used for transporting a [public invite link](https://docs.getunleash.io/reference/public-signup#public-sign-up-tokens)", "properties": { "createdAt": { + "description": "When the token was created.", + "example": "2023-04-12T11:13:31.960Z", "format": "date-time", "type": "string", }, "createdBy": { + "description": "The creator's email or username", + "example": "someone@example.com", "nullable": true, "type": "string", }, "enabled": { + "description": "Whether the token is active. This property will always be \`false\` for a token that has expired.", + "example": true, "type": "boolean", }, "expiresAt": { + "description": "The time when the token will expire.", + "example": "2023-04-12T11:13:31.960Z", "format": "date-time", "type": "string", }, "name": { + "description": "The token's name. Only for displaying in the UI", + "example": "Invite public viewers", "type": "string", }, "role": { @@ -3778,10 +3790,13 @@ Stats are divided into current and previous **windows**. "description": "Users who sign up using this token will be given this role.", }, "secret": { + "description": "The actual value of the token. This is the part that is used by Unleash to create an invite link", + "example": "a3c84b25409ea8ca1782ef17f94a42fc", "type": "string", }, "url": { "description": "The public signup link for the token. Users who follow this link will be taken to a signup page where they can create an Unleash user.", + "example": "https://sandbox.getunleash.io/enterprise/new-user?invite=a3c84b25409ea8ca1782ef17f94a42fc", "type": "string", }, "users": { @@ -3807,12 +3822,16 @@ Stats are divided into current and previous **windows**. }, "publicSignupTokenUpdateSchema": { "additionalProperties": false, + "description": "Used by Unleash for updating a token's expiration date or, when deleting the invite link, it's status", "properties": { "enabled": { + "description": "Whether the token is active or not.", + "example": true, "type": "boolean", }, "expiresAt": { "description": "The token's expiration date.", + "example": "2023-04-11T15:46:56Z", "format": "date-time", "type": "string", }, @@ -3821,8 +3840,27 @@ Stats are divided into current and previous **windows**. }, "publicSignupTokensSchema": { "additionalProperties": false, + "description": "A wrapper object containing all the public signup tokens", "properties": { "tokens": { + "description": "An array of all the public signup tokens", + "example": [ + { + "createdAt": "2023-04-12T11:13:31.960Z", + "createdBy": "someone", + "enabled": false, + "expiresAt": "2023-04-12T11:13:31.960Z", + "name": "Invite public viewers", + "role": { + "id": 3, + "name": "Viewer", + "type": "root", + }, + "secret": "a3c84b25409ea8ca1782ef17f94a42fc", + "url": "https://my_unleash_instance/new-user?invite=a3c84b25409ea8ca1782ef17f94a42fc", + "users": null, + }, + ], "items": { "$ref": "#/components/schemas/publicSignupTokenSchema", }, @@ -6518,6 +6556,7 @@ If the provided project does not exist, the list of events will be empty.", ], }, "post": { + "description": "Lets administrators create a invite link to share with colleagues. People that join using the public invite are assigned the \`Viewer\` role", "operationId": "createPublicSignupToken", "requestBody": { "content": { @@ -6550,6 +6589,15 @@ If the provided project does not exist, the list of events will be empty.", }, }, }, + "400": { + "description": "The request data does not match what we expect.", + }, + "401": { + "description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.", + }, + "403": { + "description": "User credentials are valid but does not have enough privileges to execute this operation", + }, }, "summary": "Create a public signup token", "tags": [ @@ -6582,6 +6630,12 @@ If the provided project does not exist, the list of events will be empty.", }, "description": "publicSignupTokenSchema", }, + "401": { + "description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.", + }, + "403": { + "description": "User credentials are valid but does not have enough privileges to execute this operation", + }, }, "summary": "Retrieve a token", "tags": [ @@ -6589,6 +6643,7 @@ If the provided project does not exist, the list of events will be empty.", ], }, "put": { + "description": "Update information about a specific token. The \`:token\` part of the URL should be the token's secret.", "operationId": "updatePublicSignupToken", "parameters": [ { @@ -6622,6 +6677,15 @@ If the provided project does not exist, the list of events will be empty.", }, "description": "publicSignupTokenSchema", }, + "400": { + "description": "The request data does not match what we expect.", + }, + "401": { + "description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.", + }, + "403": { + "description": "User credentials are valid but does not have enough privileges to execute this operation", + }, }, "summary": "Update a public signup token", "tags": [