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;

/**

 * A Response Example Object.

 *

 * https://spec.openapis.org/oas/v3.1.0#example-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 example extends openapi_base {

    /**

     * Create a new example.

     *

     * @param string $name The name of the example.

     * @param string|null $summary A summary of the example.

     * @param string|null $description A long description fo the example. CommonMark syntax may be used.

     * @param mixed $value Embedded literal example.

     * @param string|null $externalvalue A URI that points to the literal example.

     * @param mixed ...$extra

     * @throws coding_exception if both the value and externalvalue are null

     */

    public function __construct(

        /** @var string The name of the example */

        protected string $name,

        /** @var string|null A summary of the example */

        protected ?string $summary = null,

        /** @var string|null A long description fo the example. CommonMark syntax may be used */

        protected ?string $description = null,

        /**

         * Embedded literal example.

         *

         * The value field and externalValue field are mutually exclusive.

         * To represent examples of media types that cannot naturally represented in JSON or YAML,

         * use a string value to contain the example, escaping where necessary.

         *

         * @var mixed

         */

        protected mixed $value = null,

        /**

         * A URI that points to the literal example.

         *

         * This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.

         * The value field and externalValue field are mutually exclusive. See the rules for resolving Relative References.

         *

         * @var string|null

         */

        protected ?string $externalvalue = null,

        ...$extra,

    ) {

        if (!($value === null || $externalvalue === null)) {

            throw new coding_exception('Only one of value or externalvalue can be specified.');

        }

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

    }

    /**

     * Get the name of this example.

     *

     * @return string

     */

    public function get_name(): string {

        return $this->name;

    }

    #[\Override]

    public function get_openapi_description(

        specification $api,

        ?string $path = null,

    ): ?\stdClass {

        $data = (object) [];

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

            $data->summary = $this->summary;

        }

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

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

        }

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

            $data->value = $this->value;

        } else if ($this->externalvalue !== null) {

            $data->externalValue = $this->externalvalue;

        }

        return $data;

    }

}