Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle 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 General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core\router\schema;

use core\exception\coding_exception;

use core\param;

use core\router\route;

use core\router\schema\objects\type_base;

use stdClass;

/**

 * OpenAPI parameter.

 *

 * https://spec.openapis.org/oas/v3.1.0#parameter-object

 *

 * @package    core

 * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class parameter extends openapi_base {

    /** @var string A query parameter */

    public const IN_QUERY = 'query';

    /** @var string A header parameter */

    public const IN_HEADER = 'header';

    /** @var string A URI path parameter */

    public const IN_PATH = 'path';

    /** @var string A cookie parameter */

    public const IN_COOKIE = 'cookie';

    /**

     * Constructor for a Parameter Object.

     *

     * @param string $name The name of the parameter. Parameter names are case sensitive.

     * - If in is "path", the name field MUST correspond to a template expression occurring within the

     *   path field in the Paths Object.

     *   See Path Templating for further information.

     * - If in is "header" and the name field is "Accept", "Content-Type" or "Authorization",

     *   the parameter definition SHALL be ignored.

     * - For all other cases, the name corresponds to the parameter name used by the in property.

     * @param string $in The location of the parameter. Possible values are "query", "header", "path" or "cookie".

     * @param null|string $description

     * @param null|bool $required

     * @param null|bool $deprecated Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

     * @param null|param $type A Moodle parameter type, which can be used instead of a schema.

     * @param mixed $default The default value

     * @param null|type_base $schema

     * @param null|example $example

     * @param example[] $examples

     * @param mixed[] ...$extra

     * @throws coding_exception

     */

    public function __construct(

        /** @var string The name of the parameter. Parameter names are case sensitive */

        protected string $name,

        /** @var string The location of the parameter */

        protected string $in,

        /** @var string|null A description of the parameter */

        protected ?string $description = null,

        /** @var bool|null Whether the parameter is required */

        protected ?bool $required = null,

        /** @var bool|null Whether the parameter is deprecated */

        protected ?bool $deprecated = false,

        /** @var param|null A Moodle parameter type */

        protected ?param $type = null,

        /** @var mixed|null The default value of the parameter */

        protected mixed $default = null,

        /** @var type_base|null The schema */

        protected ?type_base $schema = null,

        /** @var example|null An example */

        protected ?example $example = null,

        /** @var example[] An array of examples */

        protected array $examples = [],

        ...$extra,

    ) {

        if ($example) {

            if (count($examples)) {

                throw new coding_exception('Only one of example or examples can be specified.');

            }

            $this->examples[$example->get_name()] = $example;

        }

        if ($required === true && $default !== null) {

            throw new coding_exception('A parameter cannot be required and have a default value.');

        }

        parent::__construct(...$extra);

    }

    #[\Override]

    public function get_openapi_description(

        specification $api,

        ?string $path = null,

    ): ?stdClass {

        $data = (object) [

            // The `name`, and `in` values are required.

            'name' => $this->name,

            'in' => $this->in,

        ];

        if ($this->description !== null) {

            $data->description = $this->description;

        }

        // Allow another schema to be passed.

        if ($this->schema !== null) {

            $data->schema = $this->schema->get_openapi_schema($api, $path);

        } else {

            $data->schema = $this->get_schema_from_type($this->type);

        }

        if (count($this->examples) > 0) {

            $data->examples = [];

            foreach ($this->examples as $example) {

                $data->examples[$example->get_name()] = $example->get_openapi_schema(

                    api: $api,

                );

            }

        }

        return $data;

    }

    /**

     * Get the OpenAPI 'in' property.

     *

     * @return string

     */

    public function get_in(): string {

        return $this->in;

    }

    /**

     * Fetch the underlying param.

     *

     * @return param

     */

    public function get_type(): param {

        return $this->type;

    }

    /**

     * Whether this property is required.

     *

     * @param route $route

     * @return bool

     */

    public function is_required(route $route): bool {

        return $this->required ?? false;

    }

    /**

     * Get the name of the parameter.

     *

     * @return string

     */

    public function get_name(): string {

        return $this->name;

    }

}