From b3cdc4fdd296141dd554dda60d8c2542e3ed0176 Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Wed, 8 Nov 2023 19:31:59 +0200 Subject: [PATCH] Update API reference responses for secrets, folders, environments, and secret imports --- backend/spec.json | 209 ++++++++++++++++-- .../controllers/v1/secretImpsController.ts | 3 +- .../controllers/v1/secretsFolderController.ts | 21 +- .../controllers/v2/environmentController.ts | 54 ++++- .../src/controllers/v3/secretsController.ts | 72 +++++- backend/swagger/index.ts | 18 ++ docs/mint.json | 4 +- docs/spec.yaml | 144 +++++++++++- 8 files changed, 483 insertions(+), 42 deletions(-) diff --git a/backend/spec.json b/backend/spec.json index 5b74ef6a1..ecb6977b5 100644 --- a/backend/spec.json +++ b/backend/spec.json @@ -2448,14 +2448,21 @@ "properties": { "id": { "type": "string", + "description": "ID of folder", "example": "someFolderId" }, "name": { "type": "string", + "description": "Name of folder", "example": "my_folder" + }, + "version": { + "type": "number", + "description": "Version of folder", + "example": 1 } }, - "description": "Details of the created folder" + "description": "Details of created folder" } } } @@ -2614,6 +2621,7 @@ "properties": { "message": { "type": "string", + "description": "Success message", "example": "Successfully updated folder" }, "folder": { @@ -2621,11 +2629,13 @@ "properties": { "name": { "type": "string", + "description": "Name of updated folder", "example": "updated_folder_name" }, "id": { "type": "string", - "example": "someFolderId" + "description": "ID of created folder", + "example": "abc123" } }, "description": "Details of the updated folder" @@ -2709,6 +2719,7 @@ "properties": { "message": { "type": "string", + "description": "Success message", "example": "successfully deleted folders" }, "folders": { @@ -2718,15 +2729,17 @@ "properties": { "id": { "type": "string", - "example": "someFolderId" + "description": "ID of deleted folder", + "example": "abc123" }, "name": { "type": "string", + "description": "Name of deleted folder", "example": "someFolderName" } } }, - "description": "List of IDs and names of the deleted folders" + "description": "List of IDs and names of deleted folders" } } } @@ -3079,8 +3092,7 @@ "type": "object", "properties": { "secretImport": { - "type": "object", - "description": "Details of a secret import" + "$ref": "#/components/schemas/SecretImport" } } } @@ -4299,7 +4311,42 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Sucess message", + "example": "Successfully created environment" + }, + "workspace": { + "type": "string", + "description": "ID of workspace where environment was created", + "example": "abc123" + }, + "environment": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of created environment", + "example": "Staging" + }, + "slug": { + "type": "string", + "description": "Slug of created environment", + "example": "staging" + } + } + } + }, + "description": "Details of the created environment" + } + } + } }, "400": { "description": "Bad Request" @@ -4360,21 +4407,25 @@ "properties": { "message": { "type": "string", + "description": "Success message", "example": "Successfully update environment" }, "workspace": { "type": "string", - "example": "someWorkspaceId" + "description": "ID of workspace where environment was updated", + "example": "abc123" }, "environment": { "type": "object", "properties": { "name": { "type": "string", + "description": "Name of updated environment", "example": "Staging-Renamed" }, "slug": { "type": "string", + "description": "Slug of updated environment", "example": "staging-renamed" } } @@ -4465,15 +4516,18 @@ "properties": { "message": { "type": "string", + "description": "Success message", "example": "Successfully deleted environment" }, "workspace": { "type": "string", - "example": "someWorkspaceId" + "description": "ID of workspace where environment was deleted", + "example": "abc123" }, "environment": { "type": "string", - "example": "dev-environment" + "description": "Slug of deleted environment", + "example": "dev" } }, "description": "Response after deleting an environment from a workspace" @@ -4484,8 +4538,7 @@ }, "security": [ { - "apiKeyAuth": [], - "bearerAuth": [] + "apiKeyAuth": [] } ], "requestBody": { @@ -5535,7 +5588,23 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "secrets": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RawSecret" + }, + "description": "List of secrets" + } + } + } + } + } } }, "security": [ @@ -5608,7 +5677,19 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "secret": { + "$ref": "#/components/schemas/RawSecret" + } + } + } + } + } } }, "security": [ @@ -5634,7 +5715,14 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RawSecret" + } + } + } } }, "security": [ @@ -5711,7 +5799,14 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RawSecret" + } + } + } } }, "security": [ @@ -5783,7 +5878,20 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "secret": { + "$ref": "#/components/schemas/RawSecret" + } + }, + "description": "The deleted secret" + } + } + } } }, "security": [ @@ -6447,6 +6555,73 @@ } } }, + "RawSecret": { + "type": "object", + "properties": { + "_id": { + "type": "string", + "example": "abc123" + }, + "version": { + "type": "number", + "example": 1 + }, + "workspace": { + "type": "string", + "example": "abc123" + }, + "environment": { + "type": "string", + "example": "dev" + }, + "secretKey": { + "type": "string", + "example": "STRIPE_KEY" + }, + "secretValue": { + "type": "string", + "example": "abc123" + }, + "secretComment": { + "type": "string", + "example": "Lorem ipsum" + } + } + }, + "SecretImport": { + "type": "object", + "properties": { + "_id": { + "type": "string", + "example": "" + }, + "workspace": { + "type": "string", + "example": "abc123" + }, + "environment": { + "type": "string", + "example": "dev" + }, + "folderId": { + "type": "string", + "example": "root" + }, + "imports": { + "type": "array", + "example": [], + "items": {} + }, + "updatedAt": { + "type": "string", + "example": "2023-01-13T14:16:12.210Z" + }, + "createdAt": { + "type": "string", + "example": "2023-01-13T14:16:12.210Z" + } + } + }, "Log": { "type": "object", "properties": { diff --git a/backend/src/controllers/v1/secretImpsController.ts b/backend/src/controllers/v1/secretImpsController.ts index 9c3dc88c4..80adfc69a 100644 --- a/backend/src/controllers/v1/secretImpsController.ts +++ b/backend/src/controllers/v1/secretImpsController.ts @@ -524,8 +524,7 @@ export const getSecretImports = async (req: Request, res: Response) => { "type": "object", "properties": { "secretImport": { - "type": "object", - "description": "Details of a secret import" + $ref: '#/definitions/SecretImport' } } } diff --git a/backend/src/controllers/v1/secretsFolderController.ts b/backend/src/controllers/v1/secretsFolderController.ts index 48a302778..af9ee5277 100644 --- a/backend/src/controllers/v1/secretsFolderController.ts +++ b/backend/src/controllers/v1/secretsFolderController.ts @@ -79,14 +79,21 @@ export const createFolder = async (req: Request, res: Response) => { "properties": { "id": { "type": "string", + "description": "ID of folder", "example": "someFolderId" }, "name": { "type": "string", + "description": "Name of folder", "example": "my_folder" + }, + "version": { + "type": "number", + "description": "Version of folder", + "example": 1 } }, - "description": "Details of the created folder" + "description": "Details of created folder" } } } @@ -275,6 +282,7 @@ export const updateFolderById = async (req: Request, res: Response) => { "properties": { "message": { "type": "string", + "description": "Success message", "example": "Successfully updated folder" }, "folder": { @@ -282,11 +290,13 @@ export const updateFolderById = async (req: Request, res: Response) => { "properties": { "name": { "type": "string", + "description": "Name of updated folder", "example": "updated_folder_name" }, "id": { "type": "string", - "example": "someFolderId" + "description": "ID of created folder", + "example": "abc123" } }, "description": "Details of the updated folder" @@ -444,6 +454,7 @@ export const deleteFolder = async (req: Request, res: Response) => { "properties": { "message": { "type": "string", + "description": "Success message", "example": "successfully deleted folders" }, "folders": { @@ -453,15 +464,17 @@ export const deleteFolder = async (req: Request, res: Response) => { "properties": { "id": { "type": "string", - "example": "someFolderId" + "description": "ID of deleted folder", + "example": "abc123" }, "name": { "type": "string", + "description": "Name of deleted folder", "example": "someFolderName" } } }, - "description": "List of IDs and names of the deleted folders" + "description": "List of IDs and names of deleted folders" } } } diff --git a/backend/src/controllers/v2/environmentController.ts b/backend/src/controllers/v2/environmentController.ts index 87c306515..130e2e225 100644 --- a/backend/src/controllers/v2/environmentController.ts +++ b/backend/src/controllers/v2/environmentController.ts @@ -70,6 +70,44 @@ export const createWorkspaceEnvironment = async (req: Request, res: Response) => } } } + + #swagger.responses[200] = { + content: { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Sucess message", + "example": "Successfully created environment" + }, + "workspace": { + "type": "string", + "description": "ID of workspace where environment was created", + "example": "abc123" + }, + "environment": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of created environment", + "example": "Staging" + }, + "slug": { + "type": "string", + "description": "Slug of created environment", + "example": "staging" + } + } + } + }, + "description": "Details of the created environment" + } + } + } + } */ const { params: { workspaceId }, @@ -249,21 +287,25 @@ export const renameWorkspaceEnvironment = async (req: Request, res: Response) => "properties": { "message": { "type": "string", + "description": "Success message", "example": "Successfully update environment" }, "workspace": { "type": "string", - "example": "someWorkspaceId" + "description": "ID of workspace where environment was updated", + "example": "abc123" }, "environment": { "type": "object", "properties": { "name": { "type": "string", + "description": "Name of updated environment", "example": "Staging-Renamed" }, "slug": { "type": "string", + "description": "Slug of updated environment", "example": "staging-renamed" } } @@ -408,8 +450,7 @@ export const deleteWorkspaceEnvironment = async (req: Request, res: Response) => #swagger.description = 'Delete environment' #swagger.security = [{ - "apiKeyAuth": [], - "bearerAuth": [] + "apiKeyAuth": [] }] #swagger.parameters['workspaceId'] = { @@ -445,15 +486,18 @@ export const deleteWorkspaceEnvironment = async (req: Request, res: Response) => "properties": { "message": { "type": "string", + "description": "Success message", "example": "Successfully deleted environment" }, "workspace": { "type": "string", - "example": "someWorkspaceId" + "description": "ID of workspace where environment was deleted", + "example": "abc123" }, "environment": { "type": "string", - "example": "dev-environment" + "description": "Slug of deleted environment", + "example": "dev" } }, "description": "Response after deleting an environment from a workspace" diff --git a/backend/src/controllers/v3/secretsController.ts b/backend/src/controllers/v3/secretsController.ts index ebd7bddd3..1cc3f1953 100644 --- a/backend/src/controllers/v3/secretsController.ts +++ b/backend/src/controllers/v3/secretsController.ts @@ -171,6 +171,25 @@ export const getSecretsRaw = async (req: Request, res: Response) => { "type": "boolean", "in": "query" } + + #swagger.responses[200] = { + content: { + "application/json": { + "schema": { + "type": "object", + "properties": { + "secrets": { + "type": "array", + "items": { + $ref: '#/definitions/RawSecret' + }, + "description": "List of secrets" + } + } + } + } + } + } */ const validatedData = await validateRequest(reqValidator.GetSecretsRawV3, req); let { @@ -313,6 +332,21 @@ export const getSecretByNameRaw = async (req: Request, res: Response) => { "type": "boolean", "in": "query" } + + #swagger.responses[200] = { + content: { + "application/json": { + "schema": { + "type": "object", + "properties": { + "secret": { + $ref: '#/definitions/RawSecret' + } + } + } + } + } + } */ const { query: { secretPath, environment, workspaceId, type, include_imports }, @@ -418,6 +452,16 @@ export const createSecretRaw = async (req: Request, res: Response) => { } } } + + #swagger.responses[200] = { + content: { + "application/json": { + "schema": { + $ref: '#/definitions/RawSecret' + } + } + } + } */ const { params: { secretName }, @@ -561,6 +605,16 @@ export const updateSecretByNameRaw = async (req: Request, res: Response) => { } } } + + #swagger.responses[200] = { + content: { + "application/json": { + "schema": { + $ref: '#/definitions/RawSecret' + } + } + } + } */ const { params: { secretName }, @@ -667,6 +721,22 @@ export const deleteSecretByNameRaw = async (req: Request, res: Response) => { } } } + + #swagger.responses[200] = { + content: { + "application/json": { + "schema": { + "type": "object", + "properties": { + "secret": { + $ref: '#/definitions/RawSecret' + } + }, + "description": "The deleted secret" + } + } + } + } */ const { params: { secretName }, @@ -1234,4 +1304,4 @@ export const deleteSecretByNameBatch = async (req: Request, res: Response) => { return res.status(200).send({ secrets: deletedSecrets }); -}; +}; \ No newline at end of file diff --git a/backend/swagger/index.ts b/backend/swagger/index.ts index 7fd4094a8..7258c727a 100644 --- a/backend/swagger/index.ts +++ b/backend/swagger/index.ts @@ -143,6 +143,24 @@ const generateOpenAPISpec = async () => { updatedAt: "2023-01-13T14:16:12.210Z", createdAt: "2023-01-13T14:16:12.210Z", }, + RawSecret: { + _id: "abc123", + version: 1, + workspace: "abc123", + environment: "dev", + secretKey: "STRIPE_KEY", + secretValue: "abc123", + secretComment: "Lorem ipsum" + }, + SecretImport: { + _id: "", + workspace: "abc123", + environment: "dev", + folderId: "root", + imports: [], + updatedAt: "2023-01-13T14:16:12.210Z", + createdAt: "2023-01-13T14:16:12.210Z" + }, Log: { _id: "", user: { diff --git a/docs/mint.json b/docs/mint.json index b42b05316..315d5438b 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -358,9 +358,7 @@ "api-reference/endpoints/secrets/create", "api-reference/endpoints/secrets/read", "api-reference/endpoints/secrets/update", - "api-reference/endpoints/secrets/delete", - "api-reference/endpoints/secrets/versions", - "api-reference/endpoints/secrets/rollback-version" + "api-reference/endpoints/secrets/delete" ] }, { diff --git a/docs/spec.yaml b/docs/spec.yaml index 06441f9cc..6f12cbdf3 100644 --- a/docs/spec.yaml +++ b/docs/spec.yaml @@ -1491,11 +1491,17 @@ paths: properties: id: type: string + description: ID of folder example: someFolderId name: type: string + description: Name of folder example: my_folder - description: Details of the created folder + version: + type: number + description: Version of folder + example: 1 + description: Details of created folder '400': description: >- Bad Request. For example, 'Folder name cannot contain spaces. Only @@ -1601,16 +1607,19 @@ paths: properties: message: type: string + description: Success message example: Successfully updated folder folder: type: object properties: name: type: string + description: Name of updated folder example: updated_folder_name id: type: string - example: someFolderId + description: ID of created folder + example: abc123 description: Details of the updated folder '400': description: >- @@ -1667,6 +1676,7 @@ paths: properties: message: type: string + description: Success message example: successfully deleted folders folders: type: array @@ -1675,11 +1685,13 @@ paths: properties: id: type: string - example: someFolderId + description: ID of deleted folder + example: abc123 name: type: string + description: Name of deleted folder example: someFolderName - description: List of IDs and names of the deleted folders + description: List of IDs and names of deleted folders '400': description: Bad Request. Reasons can include 'The folder doesn't exist' '401': @@ -1909,8 +1921,7 @@ paths: type: object properties: secretImport: - type: object - description: Details of a secret import + $ref: '#/components/schemas/SecretImport' '401': description: Unauthorized access due to invalid token or scope '403': @@ -2659,6 +2670,31 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: Sucess message + example: Successfully created environment + workspace: + type: string + description: ID of workspace where environment was created + example: abc123 + environment: + type: object + properties: + name: + type: string + description: Name of created environment + example: Staging + slug: + type: string + description: Slug of created environment + example: staging + description: Details of the created environment '400': description: Bad Request security: @@ -2700,18 +2736,22 @@ paths: properties: message: type: string + description: Success message example: Successfully update environment workspace: type: string - example: someWorkspaceId + description: ID of workspace where environment was updated + example: abc123 environment: type: object properties: name: type: string + description: Name of updated environment example: Staging-Renamed slug: type: string + description: Slug of updated environment example: staging-renamed description: Details of the renamed environment security: @@ -2769,17 +2809,19 @@ paths: properties: message: type: string + description: Success message example: Successfully deleted environment workspace: type: string - example: someWorkspaceId + description: ID of workspace where environment was deleted + example: abc123 environment: type: string - example: dev-environment + description: Slug of deleted environment + example: dev description: Response after deleting an environment from a workspace security: - apiKeyAuth: [] - bearerAuth: [] requestBody: content: application/json: @@ -3425,6 +3467,16 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + type: object + properties: + secrets: + type: array + items: + $ref: '#/components/schemas/RawSecret' + description: List of secrets security: - apiKeyAuth: [] bearerAuth: [] @@ -3472,6 +3524,13 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + type: object + properties: + secret: + $ref: '#/components/schemas/RawSecret' security: - apiKeyAuth: [] bearerAuth: [] @@ -3488,6 +3547,10 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RawSecret' security: - apiKeyAuth: [] bearerAuth: [] @@ -3544,6 +3607,10 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RawSecret' security: - apiKeyAuth: [] bearerAuth: [] @@ -3596,6 +3663,14 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + type: object + properties: + secret: + $ref: '#/components/schemas/RawSecret' + description: The deleted secret security: - apiKeyAuth: [] bearerAuth: [] @@ -4044,6 +4119,55 @@ components: createdAt: type: string example: '2023-01-13T14:16:12.210Z' + RawSecret: + type: object + properties: + _id: + type: string + example: abc123 + version: + type: number + example: 1 + workspace: + type: string + example: abc123 + environment: + type: string + example: dev + secretKey: + type: string + example: STRIPE_KEY + secretValue: + type: string + example: abc123 + secretComment: + type: string + example: Lorem ipsum + SecretImport: + type: object + properties: + _id: + type: string + example: '' + workspace: + type: string + example: abc123 + environment: + type: string + example: dev + folderId: + type: string + example: root + imports: + type: array + example: [] + items: {} + updatedAt: + type: string + example: '2023-01-13T14:16:12.210Z' + createdAt: + type: string + example: '2023-01-13T14:16:12.210Z' Log: type: object properties: