Generator.php

Go to the documentation of this file.

<?php
namespace Magento\Webapi\Model\Rest\Swagger;

use Magento\Framework\Api\SimpleDataObjectConverter;
use Magento\Framework\App\ProductMetadataInterface;
use Magento\Framework\Reflection\TypeProcessor;
use Magento\Framework\Webapi\Authorization;
use Magento\Framework\Webapi\Exception as WebapiException;
use Magento\Webapi\Controller\Rest;
use Magento\Webapi\Model\AbstractSchemaGenerator;
use Magento\Webapi\Model\Config\Converter;
use Magento\Webapi\Model\Rest\Swagger;
use Magento\Webapi\Model\Rest\SwaggerFactory;
use Magento\Webapi\Model\ServiceMetadata;

class Generator extends AbstractSchemaGenerator
{
    const ERROR_SCHEMA = '#/definitions/error-response';

    const UNAUTHORIZED_DESCRIPTION = '401 Unauthorized';

    const ARRAY_SIGNIFIER = '[0]';

    protected $swaggerFactory;

    protected $productMetadata;

    protected $tags = [];

    protected $definitions = [];

    protected $simpleTypeList = [
        'bool'                              => 'boolean',
        'boolean'                           => 'boolean',
        'int'                               => 'integer',
        'integer'                           => 'integer',
        'double'                            => 'number',
        'float'                             => 'number',
        'number'                            => 'number',
        'string'                            => 'string',
        TypeProcessor::ANY_TYPE             => 'string',
        TypeProcessor::NORMALIZED_ANY_TYPE  => 'string',
    ];

    public function __construct(
        \Magento\Webapi\Model\Cache\Type\Webapi $cache,
        \Magento\Framework\Reflection\TypeProcessor $typeProcessor,
        \Magento\Framework\Webapi\CustomAttribute\ServiceTypeListInterface $serviceTypeList,
        \Magento\Webapi\Model\ServiceMetadata $serviceMetadata,
        Authorization $authorization,
        SwaggerFactory $swaggerFactory,
        ProductMetadataInterface $productMetadata
    ) {
        $this->swaggerFactory = $swaggerFactory;
        $this->productMetadata = $productMetadata;
        parent::__construct(
            $cache,
            $typeProcessor,
            $serviceTypeList,
            $serviceMetadata,
            $authorization
        );
    }

    protected function generateSchema($requestedServiceMetadata, $requestScheme, $requestHost, $endpointUrl)
    {
        $swagger = $this->swaggerFactory->create();

        $swagger->setInfo($this->getGeneralInfo());

        $this->addCustomAttributeTypes();
        $swagger->setHost($requestHost);
        $swagger->setBasePath(strstr($endpointUrl, Rest::SCHEMA_PATH, true));
        $swagger->setSchemes([$requestScheme]);

        foreach ($requestedServiceMetadata as $serviceName => $serviceData) {
            if (!isset($this->tags[$serviceName])) {
                $this->tags[$serviceName] = $this->generateTagInfo($serviceName, $serviceData);
                $swagger->addTag($this->tags[$serviceName]);
            }
            foreach ($serviceData[Converter::KEY_ROUTES] as $uri => $httpMethods) {
                $uri = $this->convertPathParams($uri);
                foreach ($httpMethods as $httpOperation => $httpMethodData) {
                    $httpOperation = strtolower($httpOperation);
                    $phpMethodData = $serviceData[Converter::KEY_METHODS][$httpMethodData[Converter::KEY_METHOD]];
                    $httpMethodData[Converter::KEY_METHOD] = $phpMethodData;
                    $httpMethodData['uri'] = $uri;
                    $httpMethodData['httpOperation'] = $httpOperation;
                    $swagger->addPath(
                        $this->convertPathParams($uri),
                        $httpOperation,
                        $this->generatePathInfo($httpOperation, $httpMethodData, $serviceName)
                    );
                }
            }
        }
        $swagger->setDefinitions($this->getDefinitions());

        return $swagger->toSchema();
    }

    protected function getGeneralInfo()
    {
        $versionParts = explode('.', $this->productMetadata->getVersion());
        if (!isset($versionParts[0]) || !isset($versionParts[1])) {
            return []; // Major and minor version are not set - return empty response
        }
        $majorMinorVersion = $versionParts[0] . '.' . $versionParts[1];

        return [
            'version' => $majorMinorVersion,
            'title' => $this->productMetadata->getName() . ' ' . $this->productMetadata->getEdition(),
        ];
    }

    protected function generatePathInfo($methodName, $httpMethodData, $tagName)
    {
        $methodData = $httpMethodData[Converter::KEY_METHOD];

        $operationId = $this->typeProcessor->getOperationName($tagName, $methodData[Converter::KEY_METHOD]);
        $operationId .= ucfirst($methodName);

        $pathInfo = [
            'tags' => [$tagName],
            'description' => $methodData['documentation'],
            'operationId' => $operationId,
        ];

        $parameters = $this->generateMethodParameters($httpMethodData, $operationId);
        if ($parameters) {
            $pathInfo['parameters'] = $parameters;
        }
        $pathInfo['responses'] = $this->generateMethodResponses($methodData);

        return $pathInfo;
    }

    protected function generateMethodResponses($methodData)
    {
        $responses = [];

        if (isset($methodData['interface']['out']['parameters'])
            && is_array($methodData['interface']['out']['parameters'])
        ) {
            $parameters = $methodData['interface']['out']['parameters'];
            $responses = $this->generateMethodSuccessResponse($parameters, $responses);
        }

        if (isset($methodData['resources'])) {
            foreach ($methodData['resources'] as $resourceName) {
                if ($resourceName !== 'anonymous') {
                    $responses[WebapiException::HTTP_UNAUTHORIZED]['description'] = self::UNAUTHORIZED_DESCRIPTION;
                    $responses[WebapiException::HTTP_UNAUTHORIZED]['schema']['$ref'] = self::ERROR_SCHEMA;
                    break;
                }
            }
        }

        if (isset($methodData['interface']['out']['throws'])
            && is_array($methodData['interface']['out']['throws'])
        ) {
            foreach ($methodData['interface']['out']['throws'] as $exceptionClass) {
                $responses = $this->generateMethodExceptionErrorResponses($exceptionClass, $responses);
            }
        }
        $responses['default']['description'] = 'Unexpected error';
        $responses['default']['schema']['$ref'] = self::ERROR_SCHEMA;

        return $responses;
    }

    private function generateMethodParameters($httpMethodData, $operationId)
    {
        $bodySchema = [];
        $parameters = [];

        $phpMethodData = $httpMethodData[Converter::KEY_METHOD];
        if (!isset($phpMethodData['interface']['in']['parameters'])
            || !isset($httpMethodData['uri'])
            || !isset($httpMethodData['httpOperation'])
        ) {
            return [];
        }

        foreach ($phpMethodData['interface']['in']['parameters'] as $parameterName => $parameterInfo) {
            if (isset($httpMethodData['parameters'][$parameterName]['force'])
                && $httpMethodData['parameters'][$parameterName]['force']
            ) {
                continue;
            }

            if (!isset($parameterInfo['type'])) {
                return [];
            }
            $description = isset($parameterInfo['documentation']) ? $parameterInfo['documentation'] : null;

            if (strpos($httpMethodData['uri'], '{' . $parameterName . '}') !== false) {
                $parameters[] = $this->generateMethodPathParameter($parameterName, $parameterInfo, $description);
            } elseif (strtoupper($httpMethodData['httpOperation']) === 'GET') {
                $parameters = $this->generateMethodQueryParameters(
                    $parameterName,
                    $parameterInfo,
                    $description,
                    $parameters
                );
            } else {
                $bodySchema = $this->generateBodySchema(
                    $parameterName,
                    $parameterInfo,
                    $description,
                    $bodySchema
                );
            }
        }

        preg_match_all('#\\{([^\\{\\}]*)\\}#', $httpMethodData['uri'], $allPathParams);
        $remainingPathParams = array_diff(
            $allPathParams[1],
            array_keys($phpMethodData['interface']['in']['parameters'])
        );
        foreach ($remainingPathParams as $pathParam) {
            $parameters[] = [
                'name' => $pathParam,
                'in' => 'path',
                'type' => 'string',
                'required' => true
            ];
        }

        if ($bodySchema) {
            $bodyParam = [];
            $bodyParam['name'] = $operationId . 'Body';
            $bodyParam['in'] = 'body';
            $bodyParam['schema'] = $bodySchema;
            $parameters[] = $bodyParam;
        }
        return $parameters;
    }

    private function createQueryParam($name, $type, $description, $required = null)
    {
        $param = [
            'name' => $name,
            'in' => 'query',
        ];

        $param = array_merge($param, $this->getObjectSchema($type, $description));

        if (isset($required)) {
            $param['required'] = $required;
        }
        return $param;
    }

    protected function generateTagInfo($serviceName, $serviceData)
    {
        $tagInfo = [];
        $tagInfo['name'] = $serviceName;
        if (!empty($serviceData) && is_array($serviceData)) {
            $tagInfo['description'] = $serviceData[Converter::KEY_DESCRIPTION];
        }
        return $tagInfo;
    }

    protected function getObjectSchema($typeName, $description = '')
    {
        $simpleType = $this->getSimpleType($typeName);
        if ($simpleType == false) {
            $result = ['type' => 'array'];
            if (!empty($description)) {
                $result['description'] = $description;
            }
            $trimedTypeName = rtrim($typeName, '[]');
            if ($simpleType = $this->getSimpleType($trimedTypeName)) {
                $result['items'] = ['type' => $simpleType];
            } else {
                if (strpos($typeName, '[]') !== false) {
                    $result['items'] = ['$ref' => $this->getDefinitionReference($trimedTypeName)];
                } else {
                    $result = ['$ref' => $this->getDefinitionReference($trimedTypeName)];
                }
                if (!$this->isDefinitionExists($trimedTypeName)) {
                    $definitionKey = $this->toLowerCaseDashSeparated($trimedTypeName);
                    $this->definitions[$definitionKey] = [];
                    $this->definitions[$definitionKey] = $this->generateDefinition($trimedTypeName);
                }
            }
        } else {
            $result = ['type' => $simpleType];
            if (!empty($description)) {
                $result['description'] = $description;
            }
        }
        return $result;
    }

    protected function generateDefinition($typeName)
    {
        $properties = [];
        $requiredProperties = [];
        $typeData = $this->typeProcessor->getTypeData($typeName);
        if (isset($typeData['parameters'])) {
            foreach ($typeData['parameters'] as $parameterName => $parameterData) {
                $properties[$parameterName] = $this->getObjectSchema(
                    $parameterData['type'],
                    $parameterData['documentation']
                );
                if ($parameterData['required']) {
                    $requiredProperties[] = $parameterName;
                }
            }
        }
        $definition = ['type' => 'object'];
        if (isset($typeData['documentation'])) {
            $definition['description'] = $typeData['documentation'];
        }
        if (!empty($properties)) {
            $definition['properties'] = $properties;
        }
        if (!empty($requiredProperties)) {
            $definition['required'] = $requiredProperties;
        }
        return $definition;
    }

    protected function getDefinitions()
    {
        return array_merge(
            [
                'error-response' => [
                    'type' => 'object',
                    'properties' => [
                        'message' => [
                            'type' => 'string',
                            'description' => 'Error message',
                        ],
                        'errors' => [
                            '$ref' => '#/definitions/error-errors',
                        ],
                        'code' => [
                            'type' => 'integer',
                            'description' => 'Error code',
                        ],
                        'parameters' => [
                            '$ref' => '#/definitions/error-parameters',
                        ],
                        'trace' => [
                            'type' => 'string',
                            'description' => 'Stack trace',
                        ],
                    ],
                    'required' => ['message'],
                ],
                'error-errors' => [
                    'type' => 'array',
                    'description' => 'Errors list',
                    'items' => [
                        '$ref' => '#/definitions/error-errors-item',
                    ],
                ],
                'error-errors-item' => [
                    'type' => 'object',
                    'description' => 'Error details',
                    'properties' => [
                        'message' => [
                            'type' => 'string',
                            'description' => 'Error message',
                        ],
                        'parameters' => [
                            '$ref' => '#/definitions/error-parameters',
                        ],
                    ],
                ],
                'error-parameters' => [
                    'type' => 'array',
                    'description' => 'Error parameters list',
                    'items' => [
                        '$ref' => '#/definitions/error-parameters-item',
                    ],
                ],
                'error-parameters-item' => [
                    'type' => 'object',
                    'description' => 'Error parameters item',
                    'properties' => [
                        'resources' => [
                            'type' => 'string',
                            'description' => 'ACL resource',
                        ],
                        'fieldName' => [
                            'type' => 'string',
                            'description' => 'Missing or invalid field name'
                        ],
                        'fieldValue' => [
                            'type' => 'string',
                            'description' => 'Incorrect field value'
                        ],
                    ],
                ],
            ],
            $this->snakeCaseDefinitions($this->definitions)
        );
    }

    private function snakeCaseDefinitions($definitions)
    {
        foreach ($definitions as $name => $vals) {
            if (!empty($vals['properties'])) {
                $definitions[$name]['properties'] = $this->convertArrayToSnakeCase($vals['properties']);
            }
            if (!empty($vals['required'])) {
                $snakeCaseRequired = [];
                foreach ($vals['required'] as $requiredProperty) {
                    $snakeCaseRequired[] = SimpleDataObjectConverter::camelCaseToSnakeCase($requiredProperty);
                }
                $definitions[$name]['required'] = $snakeCaseRequired;
            }
        }
        return $definitions;
    }

    private function convertArrayToSnakeCase($properties)
    {
        foreach ($properties as $name => $value) {
            $snakeCaseName = SimpleDataObjectConverter::camelCaseToSnakeCase($name);
            if (is_array($value)) {
                $value = $this->convertArrayToSnakeCase($value);
            }
            unset($properties[$name]);
            $properties[$snakeCaseName] = $value;
        }
        return $properties;
    }

    protected function getDefinitionReference($typeName)
    {
        return '#/definitions/' . $this->toLowerCaseDashSeparated($typeName);
    }

    protected function toLowerCaseDashSeparated($typeName)
    {
        return strtolower(preg_replace('/(.)([A-Z])/', "$1-$2", $typeName));
    }

    protected function isDefinitionExists($typeName)
    {
        return isset($this->definitions[$this->toLowerCaseDashSeparated($typeName)]);
    }

    protected function addCustomAttributeTypes()
    {
        foreach ($this->serviceTypeList->getDataTypes() as $customAttributeClass) {
            $this->typeProcessor->register($customAttributeClass);
        }
    }

    protected function getServiceMetadata($serviceName)
    {
        return $this->serviceMetadata->getRouteMetadata($serviceName);
    }

    protected function getSimpleType($type)
    {
        if (array_key_exists($type, $this->simpleTypeList)) {
            return $this->simpleTypeList[$type];
        } else {
            return false;
        }
    }

    protected function getQueryParamNames($name, $type, $description, $prefix = '')
    {
        if ($this->typeProcessor->isTypeSimple($type)) {
            // Primitive type or array of primitive types
            return [
                $this->handlePrimitive($name, $prefix) => [
                    'type' => substr($type, -2) === '[]' ? $type : $this->getSimpleType($type),
                    'description' => $description
                ]
            ];
        }
        if ($this->typeProcessor->isArrayType($type)) {
            // Array of complex type
            $arrayType = substr($type, 0, -2);
            return $this->handleComplex($name, $arrayType, $prefix, true);
        } else {
            // Complex type
            return $this->handleComplex($name, $type, $prefix, false);
        }
    }

    private function handleComplex($name, $type, $prefix, $isArray)
    {
        $parameters = $this->typeProcessor->getTypeData($type)['parameters'];
        $queryNames = [];
        foreach ($parameters as $subParameterName => $subParameterInfo) {
            $subParameterType = $subParameterInfo['type'];
            $subParameterDescription = isset($subParameterInfo['documentation'])
                ? $subParameterInfo['documentation']
                : null;
            $subPrefix = $prefix
                ? $prefix . '[' . $name . ']'
                : $name;
            if ($isArray) {
                $subPrefix .= self::ARRAY_SIGNIFIER;
            }
            $queryNames = array_merge(
                $queryNames,
                $this->getQueryParamNames($subParameterName, $subParameterType, $subParameterDescription, $subPrefix)
            );
        }
        return $queryNames;
    }

    private function handlePrimitive($name, $prefix)
    {
        return $prefix
            ? $prefix . '[' . $name . ']'
            : $name;
    }

    private function convertPathParams($uri)
    {
        $parts = explode('/', $uri);
        $count = count($parts);
        for ($i=0; $i < $count; $i++) {
            if (strpos($parts[$i], ':') === 0) {
                $parts[$i] = '{' . substr($parts[$i], 1) . '}';
            }
        }
        return implode('/', $parts);
    }

    private function generateMethodPathParameter($parameterName, $parameterInfo, $description)
    {
        $param = [
            'name' => $parameterName,
            'in' => 'path',
            'type' => $this->getSimpleType($parameterInfo['type']),
            'required' => true
        ];
        if ($description) {
            $param['description'] = $description;
            return $param;
        }
        return $param;
    }

    private function generateMethodQueryParameters($parameterName, $parameterInfo, $description, $parameters)
    {
        $queryParams = $this->getQueryParamNames($parameterName, $parameterInfo['type'], $description);
        if (count($queryParams) === 1) {
            // handle simple query parameter (includes the 'required' field)
            $parameters[] = $this->createQueryParam(
                $parameterName,
                $parameterInfo['type'],
                $description,
                $parameterInfo['required']
            );
        } else {
            foreach ($queryParams as $name => $queryParamInfo) {
                $parameters[] = $this->createQueryParam(
                    $name,
                    $queryParamInfo['type'],
                    $queryParamInfo['description']
                );
            }
        }
        return $parameters;
    }

    private function generateBodySchema($parameterName, $parameterInfo, $description, $bodySchema)
    {
        $required = isset($parameterInfo['required']) ? $parameterInfo['required'] : null;
        /*
         * There can only be one body parameter, multiple PHP parameters are represented as different
         * properties of the body.
         */
        if ($required) {
            $bodySchema['required'][] = $parameterName;
        }
        $bodySchema['properties'][$parameterName] = $this->getObjectSchema(
            $parameterInfo['type'],
            $description
        );
        $bodySchema['type'] = 'object';
        return $bodySchema;
    }

    private function generateMethodSuccessResponse($parameters, $responses)
    {
        if (isset($parameters['result']) && is_array($parameters['result'])) {
            $description = '';
            if (isset($parameters['result']['documentation'])) {
                $description = $parameters['result']['documentation'];
            }
            $schema = [];
            if (isset($parameters['result']['type'])) {
                $schema = $this->getObjectSchema($parameters['result']['type'], $description);
            }

            // Some methods may have a non-standard HTTP success code.
            $specificResponseData = $parameters['result']['response_codes']['success'] ?? [];
            // Default HTTP success code to 200 if nothing has been supplied.
            $responseCode = $specificResponseData['code'] ?? '200';
            // Default HTTP response status to 200 Success if nothing has been supplied.
            $responseDescription = $specificResponseData['description'] ?? '200 Success.';

            $responses[$responseCode]['description'] = $responseDescription;
            if (!empty($schema)) {
                $responses[$responseCode]['schema'] = $schema;
            }
        }
        return $responses;
    }

    private function generateMethodExceptionErrorResponses($exceptionClass, $responses)
    {
        $httpCode = '500';
        $description = 'Internal Server error';
        if (is_subclass_of($exceptionClass, \Magento\Framework\Exception\LocalizedException::class)) {
            // Map HTTP codes for LocalizedExceptions according to exception type
            if (is_subclass_of($exceptionClass, \Magento\Framework\Exception\NoSuchEntityException::class)) {
                $httpCode = WebapiException::HTTP_NOT_FOUND;
                $description = '404 Not Found';
            } elseif (is_subclass_of($exceptionClass, \Magento\Framework\Exception\AuthorizationException::class)
                || is_subclass_of($exceptionClass, \Magento\Framework\Exception\AuthenticationException::class)
            ) {
                $httpCode = WebapiException::HTTP_UNAUTHORIZED;
                $description = self::UNAUTHORIZED_DESCRIPTION;
            } else {
                // Input, Expired, InvalidState exceptions will fall to here
                $httpCode = WebapiException::HTTP_BAD_REQUEST;
                $description = '400 Bad Request';
            }
        }
        $responses[$httpCode]['description'] = $description;
        $responses[$httpCode]['schema']['$ref'] = self::ERROR_SCHEMA;

        return $responses;
    }

    public function getListOfServices()
    {
        $listOfAllowedServices = [];
        foreach ($this->serviceMetadata->getServicesConfig() as $serviceName => $service) {
            foreach ($service[ServiceMetadata::KEY_SERVICE_METHODS] as $method) {
                if ($this->authorization->isAllowed($method[ServiceMetadata::KEY_ACL_RESOURCES])) {
                    $listOfAllowedServices[] = $serviceName;
                    break;
                }
            }
        }
        return $listOfAllowedServices;
    }
}