admin/twenty
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Webhook Docs (#3966)

Browse Source 
* add webhook docs, openapi v3.1, stoplight v8

* *.*
This commit is contained in:
brendanlaschke
2024-02-16 15:01:37 +01:00
committed by GitHub
parent 547145389c
commit 595b2f9e6f
10 changed files with 181 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
packages/twenty-server/src/core/open-api/open-api.service.ts
View File

@ -1,7 +1,7 @@
import { Injectable } from '@nestjs/common';
import { Request } from 'express';
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
import { TokenService } from 'src/core/auth/services/token.service';
import { ObjectMetadataService } from 'src/metadata/object-metadata/object-metadata.service';
@ -16,6 +16,7 @@ import {
computeSchemaComponents,
} from 'src/core/open-api/utils/components.utils';
import { computeSchemaTags } from 'src/core/open-api/utils/compute-schema-tags.utils';
import { computeWebhooks } from 'src/core/open-api/utils/computeWebhooks.utils';
@Injectable()
export class OpenApiService {
@ -24,7 +25,7 @@ export class OpenApiService {
private readonly objectMetadataService: ObjectMetadataService,
) {}
async generateCoreSchema(request: Request): Promise<OpenAPIV3.Document> {
async generateCoreSchema(request: Request): Promise<OpenAPIV3_1.Document> {
const schema = baseSchema();
let objectMetadataItems;
@ -46,7 +47,21 @@ export class OpenApiService {
paths[`/${item.namePlural}/{id}`] = computeSingleResultPath(item);
return paths;
}, schema.paths as OpenAPIV3.PathsObject);
}, schema.paths as OpenAPIV3_1.PathsObject);
schema.webhooks = objectMetadataItems.reduce(
(paths, item) => {
paths[`Create ${item.nameSingular}`] = computeWebhooks('create', item);
paths[`Update ${item.nameSingular}`] = computeWebhooks('update', item);
paths[`Delete ${item.nameSingular}`] = computeWebhooks('delete', item);
return paths;
},
{} as Record<
string,
OpenAPIV3_1.PathItemObject | OpenAPIV3_1.ReferenceObject
>,
);
schema.tags = computeSchemaTags(objectMetadataItems);
@ -63,7 +78,7 @@ export class OpenApiService {
return schema;
}
async generateMetaDataSchema(): Promise<OpenAPIV3.Document> {
async generateMetaDataSchema(): Promise<OpenAPIV3_1.Document> {
//TODO Add once Rest MetaData api is ready
const schema = baseSchema();

4
packages/twenty-server/src/core/open-api/utils/base-schema.utils.ts
View File

@ -1,8 +1,8 @@
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
import { computeOpenApiPath } from 'src/core/open-api/utils/path.utils';
export const baseSchema = (): OpenAPIV3.Document => {
export const baseSchema = (): OpenAPIV3_1.Document => {
return {
openapi: '3.0.3',
info: {

14
packages/twenty-server/src/core/open-api/utils/components.utils.ts
View File

@ -1,4 +1,4 @@
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
import { ObjectMetadataEntity } from 'src/metadata/object-metadata/object-metadata.entity';
import { FieldMetadataType } from 'src/metadata/field-metadata/field-metadata.entity';
@ -12,7 +12,7 @@ import {
computeOrderByParameters,
} from 'src/core/open-api/utils/parameters.utils';
type Property = OpenAPIV3.SchemaObject;
type Property = OpenAPIV3_1.SchemaObject;
type Properties = {
[name: string]: Property;
@ -99,13 +99,13 @@ const getRequiredFields = (item: ObjectMetadataEntity): string[] => {
const computeSchemaComponent = (
item: ObjectMetadataEntity,
): OpenAPIV3.SchemaObject => {
): OpenAPIV3_1.SchemaObject => {
const result = {
type: 'object',
description: item.description,
properties: getSchemaComponentsProperties(item),
example: {},
} as OpenAPIV3.SchemaObject;
} as OpenAPIV3_1.SchemaObject;
const requiredFields = getRequiredFields(item);
@ -126,20 +126,20 @@ const computeSchemaComponent = (
export const computeSchemaComponents = (
objectMetadataItems: ObjectMetadataEntity[],
): Record<string, OpenAPIV3.SchemaObject> => {
): Record<string, OpenAPIV3_1.SchemaObject> => {
return objectMetadataItems.reduce(
(schemas, item) => {
schemas[capitalize(item.nameSingular)] = computeSchemaComponent(item);
return schemas;
},
{} as Record<string, OpenAPIV3.SchemaObject>,
{} as Record<string, OpenAPIV3_1.SchemaObject>,
);
};
export const computeParameterComponents = (): Record<
string,
OpenAPIV3.ParameterObject
OpenAPIV3_1.ParameterObject
> => {
return {
idPath: computeIdPathParameter(),

4
packages/twenty-server/src/core/open-api/utils/compute-schema-tags.utils.ts
View File

@ -1,11 +1,11 @@
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
import { ObjectMetadataEntity } from 'src/metadata/object-metadata/object-metadata.entity';
import { capitalize } from 'src/utils/capitalize';
export const computeSchemaTags = (
items: ObjectMetadataEntity[],
): OpenAPIV3.TagObject[] => {
): OpenAPIV3_1.TagObject[] => {
const results = [{ name: 'General', description: 'General requests' }];
items.forEach((item) => {

74
packages/twenty-server/src/core/open-api/utils/computeWebhooks.utils.ts Normal file
View File

@ -0,0 +1,74 @@
import { OpenAPIV3_1 } from 'openapi-types';
import { ObjectMetadataEntity } from 'src/metadata/object-metadata/object-metadata.entity';
import { capitalize } from 'src/utils/capitalize';
export const computeWebhooks = (
type: 'create' | 'update' | 'delete',
item: ObjectMetadataEntity,
): OpenAPIV3_1.PathItemObject => {
return {
post: {
tags: [item.nameSingular],
security: [],
requestBody: {
description: `*${type}*.**${item.nameSingular}**, *&#42;*.**${item.nameSingular}**, *&#42;*.**&#42;**`,
content: {
'application/json': {
schema: {
type: 'object',
properties: {
targetUrl: {
type: 'string',
example: 'https://example.com/incomingWebhook',
},
eventType: {
type: 'string',
enum: [
'*.*',
'*.' + item.nameSingular,
type + '.' + item.nameSingular,
],
},
objectMetadata: {
type: 'object',
properties: {
id: {
type: 'string',
example: '370985db-22d8-4463-8e5f-2271d30913bd',
},
nameSingular: {
type: 'string',
enum: [item.nameSingular],
},
},
},
workspaceId: {
type: 'string',
example: '872cfcf1-c79f-42bc-877d-5829f06eb3f9',
},
webhookId: {
type: 'string',
example: '90056586-1228-4e03-a507-70140aa85c05',
},
eventDate: {
type: 'string',
example: '2024-02-14T11:27:01.779Z',
},
record: {
$ref: `#/components/schemas/${capitalize(item.nameSingular)}`,
},
},
},
},
},
},
responses: {
'200': {
description:
'Return a 200 status to indicate that the data was received successfully',
},
},
},
} as OpenAPIV3_1.PathItemObject;
};

4
packages/twenty-server/src/core/open-api/utils/get-error-responses.utils.ts
View File

@ -1,8 +1,8 @@
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
export const getErrorResponses = (
description: string,
): OpenAPIV3.ResponseObject => {
): OpenAPIV3_1.ResponseObject => {
return {
description,
content: {

14
packages/twenty-server/src/core/open-api/utils/parameters.utils.ts
View File

@ -1,4 +1,4 @@
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
import { OrderByDirection } from 'src/workspace/workspace-query-builder/interfaces/record.interface';
@ -7,7 +7,7 @@ import { Conjunctions } from 'src/core/api-rest/api-rest-query-builder/factories
import { DEFAULT_ORDER_DIRECTION } from 'src/core/api-rest/api-rest-query-builder/factories/input-factories/order-by-input.factory';
import { DEFAULT_CONJUNCTION } from 'src/core/api-rest/api-rest-query-builder/factories/input-factories/filter-utils/add-default-conjunction.utils';
export const computeLimitParameters = (): OpenAPIV3.ParameterObject => {
export const computeLimitParameters = (): OpenAPIV3_1.ParameterObject => {
return {
name: 'limit',
in: 'query',
@ -22,7 +22,7 @@ export const computeLimitParameters = (): OpenAPIV3.ParameterObject => {
};
};
export const computeOrderByParameters = (): OpenAPIV3.ParameterObject => {
export const computeOrderByParameters = (): OpenAPIV3_1.ParameterObject => {
return {
name: 'order_by',
in: 'query',
@ -49,7 +49,7 @@ export const computeOrderByParameters = (): OpenAPIV3.ParameterObject => {
};
};
export const computeDepthParameters = (): OpenAPIV3.ParameterObject => {
export const computeDepthParameters = (): OpenAPIV3_1.ParameterObject => {
return {
name: 'depth',
in: 'query',
@ -62,7 +62,7 @@ export const computeDepthParameters = (): OpenAPIV3.ParameterObject => {
};
};
export const computeFilterParameters = (): OpenAPIV3.ParameterObject => {
export const computeFilterParameters = (): OpenAPIV3_1.ParameterObject => {
return {
name: 'filter',
in: 'query',
@ -95,7 +95,7 @@ export const computeFilterParameters = (): OpenAPIV3.ParameterObject => {
};
};
export const computeLastCursorParameters = (): OpenAPIV3.ParameterObject => {
export const computeLastCursorParameters = (): OpenAPIV3_1.ParameterObject => {
return {
name: 'last_cursor',
in: 'query',
@ -107,7 +107,7 @@ export const computeLastCursorParameters = (): OpenAPIV3.ParameterObject => {
};
};
export const computeIdPathParameter = (): OpenAPIV3.ParameterObject => {
export const computeIdPathParameter = (): OpenAPIV3_1.ParameterObject => {
return {
name: 'id',
in: 'path',

14
packages/twenty-server/src/core/open-api/utils/path.utils.ts
View File

@ -1,4 +1,4 @@
import { OpenAPIV3 } from 'openapi-types';
import { OpenAPIV3_1 } from 'openapi-types';
import { capitalize } from 'src/utils/capitalize';
import { ObjectMetadataEntity } from 'src/metadata/object-metadata/object-metadata.entity';
@ -12,7 +12,7 @@ import { getRequestBody } from 'src/core/open-api/utils/request-body.utils';
export const computeManyResultPath = (
item: ObjectMetadataEntity,
): OpenAPIV3.PathItemObject => {
): OpenAPIV3_1.PathItemObject => {
return {
get: {
tags: [item.namePlural],
@ -44,12 +44,12 @@ export const computeManyResultPath = (
'401': { $ref: '#/components/responses/401' },
},
},
} as OpenAPIV3.PathItemObject;
} as OpenAPIV3_1.PathItemObject;
};
export const computeSingleResultPath = (
item: ObjectMetadataEntity,
): OpenAPIV3.PathItemObject => {
): OpenAPIV3_1.PathItemObject => {
return {
get: {
tags: [item.namePlural],
@ -92,10 +92,10 @@ export const computeSingleResultPath = (
'401': { $ref: '#/components/responses/401' },
},
},
} as OpenAPIV3.PathItemObject;
} as OpenAPIV3_1.PathItemObject;
};
export const computeOpenApiPath = (): OpenAPIV3.PathItemObject => {
export const computeOpenApiPath = (): OpenAPIV3_1.PathItemObject => {
return {
get: {
tags: ['General'],
@ -105,5 +105,5 @@ export const computeOpenApiPath = (): OpenAPIV3.PathItemObject => {
'200': getJsonResponse(),
},
},
} as OpenAPIV3.PathItemObject;
} as OpenAPIV3_1.PathItemObject;
};