chore: docs for public signup token tag (#3486)

<!-- 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. -->

<!-- Does it close an issue? Multiple? -->
Closes #
[1-863](https://linear.app/unleash/issue/1-836/update-endpoints-for-tag-public-signup-tokens)

<!-- (For internal contributors): Does it relate to an issue on public
roadmap? -->
<!--
Relates to [roadmap](https://github.com/orgs/Unleash/projects/10) item:
#
-->

### Important files
<!-- PRs can contain a lot of changes, but not all changes are equally
important. Where should a reviewer start looking to get an overview of
the changes? Are any files particularly important? -->


## Discussion points
<!-- Anything about the PR you'd like to discuss before it gets merged?
Got any questions or doubts? -->

---------

Signed-off-by: andreas-unleash <andreas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

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',

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: {

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,
         },

src/lib/openapi/spec/public-signup-token-update-schema.ts

@@ -2,16 +2,21 @@ 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: {
         expiresAt: {
             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: {},

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',
             },

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,13 +93,16 @@ 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',
                     ),
                     responses: {
                         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),
                     },
                 }),
             ],

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,34 +3755,48 @@ 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": {
             "$ref": "#/components/schemas/roleSchema",
             "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,13 +6630,20 @@ 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": [
           "Public signup tokens",
         ],
       },
       "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": [