EspoCRM – Open Source CRM Application
PHP calendarcontactscrmcrm-platformcrm-systemcustomer-portalcustomer-supportcustomizabledocumentsemail-marketingkanbanleadsopen-sourcephpplatformsales-automationsingle-page-applicationsupport
<?php
/************************************************************************
* This file is part of EspoCRM.
*
* EspoCRM – Open Source CRM application.
* Copyright (C) 2014-2026 EspoCRM, Inc.
* Website: https://www.espocrm.com
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* The interactive user interfaces in modified source and object code versions
* of this program must display Appropriate Legal Notices, as required under
* Section 5 of the GNU Affero General Public License version 3.
*
* In accordance with Section 7(b) of the GNU Affero General Public License version 3,
* these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
************************************************************************/
namespace Espo\Tools\OpenApi;
use Espo\Core\Acl\GlobalRestriction;
use Espo\Core\Acl\Table;
use Espo\Core\AclManager;
use Espo\Core\Exceptions\BadRequest;
use Espo\Core\Select\Where\Item\Type as WhereItemType;
use Espo\Core\Utils\DataCache;
use Espo\Core\Utils\FieldUtil;
use Espo\Core\Utils\Json;
use Espo\Core\Utils\Metadata;
use Espo\Core\Utils\Module;
use Espo\Entities\Team;
use Espo\ORM\Defs;
use Espo\ORM\Defs\Params\FieldParam;
use Espo\ORM\Name\Attribute;
use Espo\ORM\Type\RelationType;
use Espo\Tools\EntityManager\EntityManager;
use Espo\Tools\OpenApi\Provider\Params;
use ReflectionClass;
use RuntimeException;
use stdClass;
class Provider
{
private const string CACHE_KEY = 'openApiSpec';
private const string PARAM_SPEC_DISABLED = 'apiSpecDisabled';
/** @var string[] */
private array $mandatoryEntityTypeList = [
Team::ENTITY_TYPE,
];
public function __construct(
private Metadata $metadata,
private Defs $defs,
private FieldSchemaBuilderFactory $fieldSchemaBuilderFactory,
private AclManager $aclManager,
private FieldUtil $fieldUtil,
private DataCache $dataCache,
private Module $module,
) {}
/**
* @throws BadRequest
*/
public function get(Params $params): string
{
$this->validateParams($params);
$params = $this->sanitizeParams($params);
$data = $this->getData($params);
return Json::encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
}
private function getData(Params $params): stdClass
{
$cacheKey = $this->getCacheKey($params);
if ($this->dataCache->has($cacheKey)) {
$data = $this->dataCache->get($cacheKey);
if ($data !== null && !$data instanceof stdClass) {
throw new RuntimeException("Corrupted OpenAPI spec cache file.");
}
if ($data !== null) {
return $data;
}
}
$data = $this->buildData($params);
$this->dataCache->store($cacheKey, $data);
return $data;
}
private function buildData(Params $params): stdClass
{
$title = 'EspoCRM API';
if ($params->module) {
$title = "EspoCRM · $params->module API";
}
$spec = (object) [
'openapi' => '3.1.1',
'info' => [
'title' => $title,
'version' => '1.0.0',
],
'paths' => [],
'components' => [
'schemas' => $this->buildSchemas($params),
'securitySchemes' => [
'ApiKeyAuth' => [
'type' => 'apiKey',
'in' => 'header',
'name' => 'X-Api-Key',
],
]
],
'security' => [
['ApiKeyAuth' => []],
],
'servers' => [
[
'url' => '{siteUrl}/api/v1',
'variables' => [
'siteUrl' => [
'default' => 'http://localhost',
'description' => 'An URL of you Espo instance.'
]
]
]
]
];
$this->buildCrud($params, $spec);
return $spec;
}
private function getCacheKey(Params $params): string
{
$key = self::CACHE_KEY;
if ($params->module !== null) {
$key .= '_' . $params->module;
return $key;
}
if ($params->skipCustom) {
$key .= '_skipCustom';
}
return $key;
}
/**
* @return array<string, array<string, mixed>>
*/
private function buildSchemas(Params $params): array
{
$output = [];
foreach ($this->getEntityTypeList($params) as $entityType) {
$entitySchemaName = $this->composeEntityTypeObjectSchemaName($entityType);
$schema = $this->buildEntityTypeObjectSchema($params, $entityType);
$required = $schema['required'];
unset($schema['required']);
$output[$entitySchemaName] = $schema;
$createSchema = [
'$ref' => "#/components/schemas/$entitySchemaName",
'type' => Type::OBJECT,
];
$createSchema['required'] = $required;
if (!$createSchema['required']) {
unset($createSchema['required']);
}
$output[$entitySchemaName . '_create'] = $createSchema;
}
$output['whereItem'] = $this->buildWhereItemSchema();
return $output;
}
/**
* @return string[]
*/
private function getEntityTypeList(Params $params): array
{
/** @var array<string, array<string, mixed>> $defs */
$defs = $this->metadata->get('scopes') ?? [];
$output = [];
foreach ($defs as $scope => $it) {
$object = $it['object'] ?? false;
$entity = $it['entity'] ?? false;
$disabled = $it['disabled'] ?? false;
$module = $it['module'] ?? false;
if ($params->module !== null && $params->module !== $module) {
continue;
}
if ($params->skipCustom && $module === EntityManager::MODULE_CUSTOM) {
continue;
}
if (!$entity) {
continue;
}
if (!$object && !in_array($scope, $this->mandatoryEntityTypeList)) {
continue;
}
if ($disabled) {
continue;
}
$output[] = $scope;
}
usort($output, function ($a, $b) {
return strcmp($a, $b);
});
return $output;
}
private function composeEntityTypeObjectSchemaName(string $entityType): string
{
return $entityType;
}
/**
* @return array{'type': string, 'required': string[], 'properties': array<string, mixed>}
*/
private function buildEntityTypeObjectSchema(Params $params, string $entityType): array
{
$fieldDefsList = $this->defs->getEntity($entityType)->getFieldList();
$forbiddenList = $this->aclManager->getScopeRestrictedFieldList($entityType, GlobalRestriction::TYPE_FORBIDDEN);
$internalList = $this->aclManager->getScopeRestrictedFieldList($entityType, GlobalRestriction::TYPE_INTERNAL);
$readOnlyList = $this->aclManager->getScopeRestrictedFieldList($entityType, [
GlobalRestriction::TYPE_READ_ONLY,
GlobalRestriction::TYPE_NON_ADMIN_READ_ONLY,
GlobalRestriction::TYPE_ONLY_ADMIN,
]);
$properties = [];
$id = $this->buildEntityTypeObjectFieldSchema($entityType, Attribute::ID);
$properties = array_merge($properties, $id->properties);
$required = [];
foreach ($fieldDefsList as $fieldDefs) {
$field = $fieldDefs->getName();
if (in_array($field, $forbiddenList)) {
continue;
}
if ($params->skipCustom && $fieldDefs->getParam('isCustom')) {
continue;
}
if (
$fieldDefs->getParam(FieldParam::DISABLED) ||
$fieldDefs->getParam(FieldParam::UTILITY) ||
$fieldDefs->getParam(self::PARAM_SPEC_DISABLED)
) {
continue;
}
$isReadOnly = in_array($field, $readOnlyList);
$isInternal = in_array($field, $internalList);
$itResult = $this->buildEntityTypeObjectFieldSchema($entityType, $field);
foreach ($itResult->properties as $attribute => $attributeSchema) {
if ($isReadOnly) {
$attributeSchema['readOnly'] = true;
}
if ($isInternal) {
$attributeSchema['writeOnly'] = true;
}
$properties[$attribute] = $attributeSchema;
}
foreach ($itResult->required as $attribute) {
$required[] = $attribute;
}
$required = array_unique($required);
$required = array_values($required);
}
return [
'type' => Type::OBJECT,
'properties' => $properties,
'required' => $required,
];
}
private function buildEntityTypeObjectFieldSchema(string $entityType, string $field): FieldSchemaResult
{
$builder = $this->fieldSchemaBuilderFactory->create($entityType, $field);
return $builder->build($entityType, $field);
}
private function buildCrud(Params $params, stdClass $spec): void
{
foreach ($this->getEntityTypeList($params) as $entityType) {
$this->buildCrudForEntityType($params, $spec, $entityType);
}
}
private function buildCrudForEntityType(Params $params, stdClass $spec, string $entityType): void
{
$pathItemRoot = (object) [];
$pathItemRoot->post = $this->prepareOperationCreate($entityType);
$pathItemRoot->get = $this->prepareOperationList($params, $entityType);
$pathItemRecord = (object) [
'parameters' => [
[
'name' => 'id',
'in' => 'path',
'required' => true,
'schema' => [
'type' => Type::STRING,
],
'description' => 'A record ID.',
]
]
];
$pathItemRecord->get = $this->prepareOperationGet($entityType);
$pathItemRecord->patch = $this->prepareOperationPatch($entityType);
$pathItemRecord->delete = $this->prepareOperationDelete($entityType);
$aclActionList = $this->metadata->get("scopes.$entityType.aclActionList");
$noRead = false;
if (is_array($aclActionList)) {
if (!in_array(Table::ACTION_CREATE, $aclActionList)) {
unset($pathItemRoot->post);
}
if (!in_array(Table::ACTION_READ, $aclActionList)) {
unset($pathItemRoot->get);
unset($pathItemRecord->get);
$noRead = true;
}
if (!in_array(Table::ACTION_EDIT, $aclActionList)) {
unset($pathItemRecord->patch);
}
if (!in_array(Table::ACTION_DELETE, $aclActionList)) {
unset($pathItemRecord->delete);
}
}
$spec->paths["/$entityType"] = get_object_vars($pathItemRoot);
$spec->paths["/$entityType/{id}"] = get_object_vars($pathItemRecord);
if (!$noRead) {
$this->addLinks($params, $entityType, $spec);
}
}
private function getEntityTypeRef(string $entityType): string
{
return "#/components/schemas/$entityType";
}
/**
* @return array<string, mixed>
*/
private function prepareOperationCreate(string $entityType): array
{
$ref = $this->getEntityTypeRef($entityType);
$createOperation = [
'tags' => [$entityType],
'requestBody' => [
'content' => [
'application/json' => [
'schema' => [
'$ref' => $ref . '_create',
],
]
]
],
'parameters' => [
[
'in' => 'header',
'name' => 'X-Skip-Duplicate-Check',
'schema' => [
'type' => Type::STRING,
'enum' => [
'true',
'false',
],
],
'description' => 'Skip duplicate check.'
],
[
'in' => 'header',
'name' => 'X-Duplicate-Source-Id',
'schema' => [
'type' => Type::STRING,
],
'description' => 'A record ID of the entity that is being duplicated.',
]
],
'summary' => "Create $entityType",
'description' => "Create a new '$entityType' record.",
];
$responses = [];
$responses['200'] = [
'content' => [
'application/json' => [
'schema' => [
'$ref' => $ref,
],
],
],
'description' => 'Success.',
];
$responses['400'] = [
'description' => 'Bad request. Might be a validation error. Check logs for details.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
$responses['409'] = [
'description' => 'Conflict. May be a possible duplicate. Use X-Skip-Duplicate-Check to skip check.',
];
$createOperation['responses'] = $responses;
return $createOperation;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationPatch(string $entityType): array
{
$ref = $this->getEntityTypeRef($entityType);
$parameters = [];
if ($this->metadata->get(['recordDefs', $entityType, 'updateDuplicateCheck']) ) {
$parameters[] =
[
'in' => 'header',
'name' => 'X-Skip-Duplicate-Check',
'schema' => [
'type' => Type::STRING,
'enum' => [
'true',
'false',
],
],
'description' => 'Skip duplicate check.'
];
}
if ($this->metadata->get(['entityDefs', $entityType, 'optimisticConcurrencyControl'])) {
$parameters[] =
[
'in' => 'header',
'name' => 'X-Version-Number',
'schema' => [
'type' => Type::STRING,
],
'description' => "A version number for optimistic concurrency control. " .
"Obtained from the 'versionNumber' field."
];
}
$operation = [
'tags' => [$entityType],
'requestBody' => [
'content' => [
'application/json' => [
'schema' => ['$ref' => $ref],
]
]
],
'parameters' => $parameters,
'summary' => "Update $entityType",
'description' => "Update an existing '$entityType' record.",
];
$responses = [];
$responses['200'] = [
'content' => [
'application/json' => [
'schema' => [
'$ref' => $ref,
],
],
],
'description' => 'Success.',
];
$responses['400'] = [
'description' => 'Bad request. Might be a validation error. Check logs for details.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
$responses['409'] = [
'description' => 'Conflict.',
];
$operation['responses'] = $responses;
return $operation;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationDelete(string $entityType): array
{
$operation = [
'tags' => [$entityType],
'summary' => "Remove $entityType",
'description' => "Remove an existing '$entityType' record.",
];
$responses = [];
$responses['200'] = [
'content' => [
'application/json' => [
'schema' => [
'type' => Type::BOOLEAN,
'description' => 'Always true. Do not check the value.',
],
],
],
'description' => 'Success.',
];
$responses['400'] = [
'description' => 'Bad request. Check logs for details.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
$operation['responses'] = $responses;
return $operation;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationGet(string $entityType): array
{
$ref = $this->getEntityTypeRef($entityType);
$operation = [
'tags' => [$entityType],
'summary' => "Read $entityType",
'description' => "Read an existing '$entityType' record.",
];
$responses = [];
$responses['200'] = [
'content' => [
'application/json' => [
'schema' => [
'$ref' => $ref,
],
],
],
'description' => 'Success.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
$operation['responses'] = $responses;
return $operation;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationList(Params $params, string $entityType): array
{
$parameters = [];
$parameters[] =
[
'in' => 'header',
'name' => 'X-No-Total',
'schema' => [
'type' => Type::STRING,
'enum' => [
'true',
'false',
],
],
'description' => 'Disable calculation of the total number of records.',
];
$parameters = array_merge($parameters, $this->prepareSearchParameters($params, $entityType));
return [
'tags' => [$entityType],
'parameters' => $parameters,
'summary' => "List $entityType",
'description' => "List $entityType records.",
'responses' => $this->prepareListResponses($entityType),
];
}
/**
* @return string[]
*/
private function getSelectAttributeList(Params $params, string $entityType): array
{
$fieldDefsList = $this->defs->getEntity($entityType)->getFieldList();
$ignoreList = $this->aclManager->getScopeRestrictedFieldList($entityType, [
GlobalRestriction::TYPE_FORBIDDEN,
GlobalRestriction::TYPE_INTERNAL,
]);
$output = [];
foreach ($fieldDefsList as $fieldDefs) {
if (in_array($fieldDefs->getName(), $ignoreList)) {
continue;
}
if ($params->skipCustom && $fieldDefs->getParam('isCustom')) {
continue;
}
$output = array_merge(
$output,
$this->fieldUtil->getAttributeList($entityType, $fieldDefs->getName())
);
}
$output = array_unique($output);
return array_values($output);
}
/**
* @return array<string, mixed>
*/
private function buildWhereItemSchema(): array
{
$whereItemTypes = array_values((new ReflectionClass(WhereItemType::class))->getConstants());
return [
'type' => Type::OBJECT,
'properties' => [
'type' => [
'type' => Type::STRING,
'enum' => $whereItemTypes,
'description' => 'An operator.',
],
'attribute' => [
'type' => Type::STRING,
'description' => 'An attribute or field.',
],
'value' => [
'oneOf' => [
[
'type' => [
Type::STRING,
Type::INTEGER,
Type::NUMBER,
Type::BOOLEAN,
Type::NULL,
]
],
[
'type' => Type::ARRAY,
'items' => [
'$ref' => '#/components/schemas/whereItem',
]
],
[
'type' => Type::ARRAY,
'items' => [
'type' => Type::STRING,
],
],
],
'description' => 'A value. A scalar, or an array of strings.',
],
'dateTime' => [
'type' => Type::BOOLEAN,
'description' => "Set true for date-time fields.",
],
"timeZone" => [
'type' => Type::STRING,
'description' => "A time zone. For date-time fields.",
],
],
'required' => ['type'],
'description' => 'A where item.',
];
}
/**
* @return array<string, mixed>[]
*/
private function prepareSearchParameters(Params $params, string $entityType): array
{
$parameters = [
[
'name' => 'offset',
'in' => 'query',
'schema' => [
'type' => Type::INTEGER,
'minimum' => 0,
],
'description' => 'A pagination offset.',
],
[
'name' => 'maxSize',
'in' => 'query',
'schema' => [
'type' => Type::INTEGER,
'minimum' => 0,
'maximum' => 200,
],
'description' => 'The maximum number of records to return.',
],
[
'name' => 'orderBy',
'in' => 'query',
'schema' => [
'type' => Type::STRING,
],
'description' => 'An attribute (field) to order by.',
],
[
'name' => 'order',
'in' => 'query',
'schema' => [
'type' => Type::STRING,
'enum' => [
'asc',
'desc',
],
],
'description' => 'An order direction.',
],
[
'name' => 'textFilter',
'in' => 'query',
'schema' => [
'type' => Type::STRING,
],
'description' => 'A text filter query. Wildcard (*) is supported.'
],
];
$primaryFilterList = array_keys($this->metadata->get("selectDefs.$entityType.primaryFilterClassNameMap") ?? []);
$boolFilterList = array_map(
function ($it) {
if (is_array($it)) {
return $it['name'] ?? null;
}
return $it;
},
$this->metadata->get("clientDefs.$entityType.boolFilterList") ?? []
);
if ($primaryFilterList) {
$parameters[] = [
'name' => 'primaryFilter',
'in' => 'query',
'schema' => [
'type' => Type::STRING,
'enum' => $primaryFilterList,
],
'description' => 'A primary filter.',
];
}
if ($boolFilterList) {
$parameters[] = [
'name' => 'boolFilterList',
'in' => 'query',
'schema' => [
'type' => Type::ARRAY,
'items' => [
'type' => Type::STRING,
'enum' => $boolFilterList,
],
],
'style' => 'deepObject',
'explode' => true,
'description' => 'Bool filters.',
];
}
$selectAttributeList = $this->getSelectAttributeList($params, $entityType);
if ($selectAttributeList) {
$parameters[] = [
'name' => 'attributeSelect',
'in' => 'query',
'schema' => [
'type' => Type::ARRAY,
'items' => [
'type' => Type::STRING,
'enum' => $selectAttributeList,
],
],
'style' => 'form',
'explode' => false,
'description' => 'Attributes to return. Select only the necessary ones to improve performance.',
];
}
$parameters[] = [
'name' => 'whereGroup',
'in' => 'query',
'schema' => [
'type' => Type::ARRAY,
'items' => [
'$ref' => '#/components/schemas/whereItem',
],
],
'style' => 'deepObject',
'explode' => true,
'description' => 'Where items.',
];
return $parameters;
}
/**
* @return array<string, mixed>
*/
private function prepareList200Response(string $entityType): array
{
$ref = $this->getEntityTypeRef($entityType);
return [
'content' => [
'application/json' => [
'schema' => [
'type' => Type::OBJECT,
'properties' => [
'list' => [
'type' => Type::ARRAY,
'items' => [
'$ref' => $ref,
],
'description' => 'Records.'
],
'total' => [
'type' => Type::NUMBER,
'description' => "The total number of records. " .
"If the total number is disabled, special values are returned: " .
"-1 – there are more records to paginate, -2 – there are no more records."
],
],
],
],
],
'description' => 'Success.',
];
}
/**
* @return array<string|int, mixed>
*/
private function prepareListResponses(string $entityType): array
{
$responses = [];
$responses['200'] = $this->prepareList200Response($entityType);
$responses['400'] = [
'description' => 'Bad request. Check logs for details.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
return $responses;
}
private function addLinks(Params $params, string $entityType, stdClass $spec): void
{
$relationList = $this->defs->getEntity($entityType)->getRelationList();
usort($relationList, function (Defs\RelationDefs $a, Defs\RelationDefs $b) {
return strcmp($a->getName(), $b->getName());
});
$restrictedList = $this->aclManager->getScopeRestrictedLinkList($entityType, [
GlobalRestriction::TYPE_FORBIDDEN,
]);
foreach ($relationList as $defs) {
$link = $defs->getName();
if (
in_array($link, $restrictedList) ||
!in_array($defs->getType(), [
RelationType::HAS_MANY,
RelationType::MANY_MANY,
RelationType::HAS_CHILDREN,
]) ||
(
$this->metadata->get("entityDefs.$entityType.links.$link.readOnly") ||
$this->metadata->get("entityDefs.$entityType.links.$link.disabled")
) ||
$params->skipCustom && $defs->getParam('isCustom') ||
$this->metadata->get("entityDefs.$entityType.links.$link." . self::PARAM_SPEC_DISABLED)
) {
continue;
}
$foreignEntityType = $this->defs
->getEntity($entityType)
->tryGetRelation($link)
?->tryGetForeignEntityType();
if (!$foreignEntityType) {
continue;
}
$this->addLink($params, $entityType, $link, $spec);
}
}
private function addLink(Params $params, string $entityType, string $link, stdClass $spec): void
{
$foreignEntityType = $this->defs
->getEntity($entityType)
->getRelation($link)
->getForeignEntityType();
if (!in_array($foreignEntityType, $this->getEntityTypeList($params))) {
return;
}
$pathItem = [
'parameters' => [
[
'name' => 'id',
'in' => 'path',
'required' => true,
'schema' => [
'type' => Type::STRING,
],
'description' => 'A record ID.',
]
]
];
$pathItem['get'] = $this->prepareOperationListLink($params, $entityType, $link, $foreignEntityType);
$pathItem['post'] = $this->prepareOperationPostLink($entityType, $link, $foreignEntityType);
$pathItem['delete'] = $this->prepareOperationDeleteLink($entityType, $link, $foreignEntityType);
$spec->paths["/$entityType/{id}/$link"] = $pathItem;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationListLink(
Params $params,
string $entityType,
string $link,
string $foreignEntityType,
): array {
$parameters = [];
$parameters = array_merge($parameters, $this->prepareSearchParameters($params, $foreignEntityType));
$operation = [
'tags' => [$entityType],
'parameters' => $parameters,
'summary' => "List $entityType . $link",
'description' => "List '$foreignEntityType' records related through the '$link' link.",
];
$responses = $this->prepareListResponses($foreignEntityType);
$operation['responses'] = $responses;
return $operation;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationPostLink(string $entityType, string $link, string $foreignEntityType): array
{
$createOperation = [
'tags' => [$entityType],
'requestBody' => [
'content' => [
'application/json' => [
'schema' => [
'type' => Type::OBJECT,
'properties' => [
'id' => [
'type' => Type::STRING,
'description' => "An ID of $foreignEntityType record.",
],
]
]
]
]
],
'summary' => "Relate $entityType . $link",
'description' => "Relate '$foreignEntityType' record though the '$link' link.",
];
$responses = [];
$responses['200'] = [
'description' => 'Success.',
];
$responses['400'] = [
'description' => 'Bad request. Might be a validation error. Check logs for details.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
$createOperation['responses'] = $responses;
return $createOperation;
}
/**
* @return array<string, mixed>
*/
private function prepareOperationDeleteLink(string $entityType, string $link, string $foreignEntityType): array
{
$createOperation = [
'tags' => [$entityType],
'requestBody' => [
'content' => [
'application/json' => [
'schema' => [
'type' => Type::OBJECT,
'properties' => [
'id' => [
'type' => Type::STRING,
'description' => "An ID of $foreignEntityType record.",
],
]
]
]
]
],
'summary' => "Unrelate $entityType . $link",
'description' => "Unrelate '$foreignEntityType' record related though the '$link' link.",
];
$responses = [];
$responses['200'] = [
'description' => 'Success.',
];
$responses['400'] = [
'description' => 'Bad request. Might be a validation error. Check logs for details.',
];
$responses['403'] = [
'description' => 'Forbidden. Might be an access control error. Check logs for details.',
];
$createOperation['responses'] = $responses;
return $createOperation;
}
/**
* @throws BadRequest
*/
private function validateParams(Params $params): void
{
if (
$params->module !== null &&
!in_array($params->module, $this->module->getList())
) {
throw new BadRequest("Module does not exist.");
}
}
private function sanitizeParams(Params $params): Params
{
if ($params->module !== null) {
$params = $params->withSkipCustom(true);
}
return $params;
}
}