Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-06-04 01:18:20 +02:00
Code Issues Projects Releases Wiki Activity

docs: openapi schema for PATs (#3605)

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

OpenAPI schema updates for Personal Access Tokens, http statuses,
property types and examples, return types

---------

Co-authored-by: Nuno Góis <github@nunogois.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
This commit is contained in:
David Leek 2023-05-11 09:11:17 +02:00 committed by GitHub
parent 36539c8e1c
commit 546f9953a7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 326 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/lib/openapi/meta-schema-rules.test.ts
View File

@ -128,8 +128,6 @@ const metaRules: Rule[] = [
'overrideSchema',
'passwordSchema',
'patchSchema',
'patSchema',
'patsSchema',
'permissionSchema',
'playgroundFeatureSchema',
'playgroundRequestSchema',
@ -241,8 +239,6 @@ const metaRules: Rule[] = [
'passwordSchema',
'patchesSchema',
'patchSchema',
'patSchema',
'patsSchema',
'permissionSchema',
'playgroundSegmentSchema',
'playgroundStrategySchema',

21
src/lib/openapi/spec/pat-schema.ts
View File

@ -3,27 +3,42 @@ import { FromSchema } from 'json-schema-to-ts';
export const patSchema = {
$id: '#/components/schemas/patSchema',
type: 'object',
description:
'An overview of a [Personal Access Token](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens).',
properties: {
id: {
type: 'number',
type: 'integer',
description:
'The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)',
example: 1,
minimum: 1,
},
secret: {
type: 'string',
description:
'The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)',
example: 'user:xyzrandomstring',
},
expiresAt: {
type: 'string',
format: 'date-time',
nullable: true,
description: `The token's expiration date.`,
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. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)',
},
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 it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)',
},
},
components: {

3
src/lib/openapi/spec/pats-schema.ts
View File

@ -4,12 +4,15 @@ import { patSchema } from './pat-schema';
export const patsSchema = {
$id: '#/components/schemas/patsSchema',
type: 'object',
description:
'Contains a collection of [Personal Access Tokens](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens).',
properties: {
pats: {
type: 'array',
items: {
$ref: '#/components/schemas/patSchema',
},
description: 'A collection of Personal Access Tokens',
},
},
components: {

37
src/lib/routes/admin-api/user/pat.ts
View File

@ -7,7 +7,11 @@ import {
IUnleashServices,
} from '../../../types';
import { createRequestSchema } from '../../../openapi/util/create-request-schema';
import { createResponseSchema } from '../../../openapi/util/create-response-schema';
import {
createResponseSchema,
resourceCreatedResponseSchema,
} from '../../../openapi/util/create-response-schema';
import { getStandardResponses } from '../../../openapi/util/standard-responses';
import { OpenApiService } from '../../../services/openapi-service';
import { emptyResponse } from '../../../openapi/util/standard-responses';
@ -15,8 +19,8 @@ import PatService from '../../../services/pat-service';
import { NONE } from '../../../types/permissions';
import { IAuthRequest } from '../../unleash-types';
import { serializeDates } from '../../../types/serialize-dates';
import { PatSchema, patSchema } from '../../../openapi/spec/pat-schema';
import { patsSchema } from '../../../openapi/spec/pats-schema';
import { patSchema } from '../../../openapi/spec/pat-schema';
import { PatsSchema, patsSchema } from '../../../openapi/spec/pats-schema';
export default class PatController extends Controller {
private patService: PatService;
@ -48,7 +52,14 @@ export default class PatController extends Controller {
openApiService.validPath({
tags: ['Personal access tokens'],
operationId: 'getPats',
responses: { 200: createResponseSchema('patsSchema') },
summary:
'Get all Personal Access Tokens for the current user.',
description:
'Returns all of the [Personal Access Tokens](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens) belonging to the current user.',
responses: {
200: createResponseSchema('patsSchema'),
...getStandardResponses(401, 403, 404),
},
}),
],
});
@ -61,8 +72,14 @@ export default class PatController extends Controller {
openApiService.validPath({
tags: ['Personal access tokens'],
operationId: 'createPat',
summary: 'Create a new Personal Access Token.',
description:
'Creates a new [Personal Access Token](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens) for the current user.',
requestBody: createRequestSchema('patSchema'),
responses: { 200: createResponseSchema('patSchema') },
responses: {
201: resourceCreatedResponseSchema('patSchema'),
...getStandardResponses(401, 403, 404),
},
}),
],
});
@ -77,7 +94,13 @@ export default class PatController extends Controller {
openApiService.validPath({
tags: ['Personal access tokens'],
operationId: 'deletePat',
responses: { 200: emptyResponse },
summary: 'Delete a Personal Access Token.',
description:
'This endpoint allows for deleting a [Personal Access Token](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens) belonging to the current user.',
responses: {
200: emptyResponse,
...getStandardResponses(401, 403, 404),
},
}),
],
});
@ -103,7 +126,7 @@ export default class PatController extends Controller {
);
}
async getPats(req: IAuthRequest, res: Response<PatSchema>): Promise<void> {
async getPats(req: IAuthRequest, res: Response<PatsSchema>): Promise<void> {
if (this.flagResolver.isEnabled('personalAccessTokensKillSwitch')) {
res.status(404).send({ message: 'PAT is disabled' });
return;

280
src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap
View File

@ -3050,24 +3050,34 @@ The provider you choose for your addon dictates what properties the \`parameters
"type": "object",
},
"patSchema": {
"description": "An overview of a [Personal Access Token](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens).",
"properties": {
"createdAt": {
"description": "When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)",
"example": "2023-04-19T08:15:14.000Z",
"format": "date-time",
"nullable": true,
"type": "string",
},
"expiresAt": {
"description": "The token's expiration date.",
"example": "2023-04-19T08:15:14.000Z",
"format": "date-time",
"nullable": true,
"type": "string",
},
"id": {
"type": "number",
"description": "The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)",
"example": 1,
"minimum": 1,
"type": "integer",
},
"secret": {
"description": "The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)",
"example": "user:xyzrandomstring",
"type": "string",
},
"seenAt": {
"description": "When the token was last seen/used to authenticate with. \`null\` if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)",
"example": "2023-04-19T08:15:14.000Z",
"format": "date-time",
"nullable": true,
"type": "string",
@ -3108,8 +3118,10 @@ The provider you choose for your addon dictates what properties the \`parameters
"type": "array",
},
"patsSchema": {
"description": "Contains a collection of [Personal Access Tokens](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens).",
"properties": {
"pats": {
"description": "A collection of Personal Access Tokens",
"items": {
"$ref": "#/components/schemas/patSchema",
},
@ -11942,6 +11954,7 @@ If the provided project does not exist, the list of events will be empty.",
},
"/api/admin/user/tokens": {
"get": {
"description": "Returns all of the [Personal Access Tokens](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens) belonging to the current user.",
"operationId": "getPats",
"responses": {
"200": {
@ -11954,12 +11967,95 @@ If the provided project does not exist, the list of events will be empty.",
},
"description": "patsSchema",
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
"404": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "Could not find the addon with ID "12345".",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NotFoundError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The requested resource was not found.",
},
},
"summary": "Get all Personal Access Tokens for the current user.",
"tags": [
"Personal access tokens",
],
},
"post": {
"description": "Creates a new [Personal Access Token](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens) for the current user.",
"operationId": "createPat",
"requestBody": {
"content": {
@ -11973,7 +12069,7 @@ If the provided project does not exist, the list of events will be empty.",
"required": true,
},
"responses": {
"200": {
"201": {
"content": {
"application/json": {
"schema": {
@ -11981,9 +12077,100 @@ If the provided project does not exist, the list of events will be empty.",
},
},
},
"description": "patSchema",
"description": "The resource was successfully created.",
"headers": {
"location": {
"description": "The location of the newly created resource.",
"schema": {
"format": "uri",
"type": "string",
},
},
},
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
"404": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "Could not find the addon with ID "12345".",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NotFoundError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The requested resource was not found.",
},
},
"summary": "Create a new Personal Access Token.",
"tags": [
"Personal access tokens",
],
@ -11991,6 +12178,7 @@ If the provided project does not exist, the list of events will be empty.",
},
"/api/admin/user/tokens/{id}": {
"delete": {
"description": "This endpoint allows for deleting a [Personal Access Token](https://docs.getunleash.io/how-to/how-to-create-personal-access-tokens) belonging to the current user.",
"operationId": "deletePat",
"parameters": [
{
@ -12006,7 +12194,89 @@ If the provided project does not exist, the list of events will be empty.",
"200": {
"description": "This response has no body.",
},
"401": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "AuthenticationRequired",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "Authorization information is missing or invalid. Provide a valid API token as the \`authorization\` header, e.g. \`authorization:*.*.my-admin-token\`.",
},
"403": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NoAccessError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "User credentials are valid but does not have enough privileges to execute this operation",
},
"404": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "The ID of the error instance",
"example": "9c40958a-daac-400e-98fb-3bb438567008",
"type": "string",
},
"message": {
"description": "A description of what went wrong.",
"example": "Could not find the addon with ID "12345".",
"type": "string",
},
"name": {
"description": "The name of the error kind",
"example": "NotFoundError",
"type": "string",
},
},
"type": "object",
},
},
},
"description": "The requested resource was not found.",
},
},
"summary": "Delete a Personal Access Token.",
"tags": [
"Personal access tokens",
],