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 coding_exception;

use core\param;

use core\router\schema\objects\type_base;

use core\router\schema\response\response;

use stdClass;

/**

 * A generic part of the OpenAPI Schema object.

 *

 * @package    core

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

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

 */

abstract class openapi_base {

    /**

     * Base constructor which does nothing.

     *

     * We keep an $extra parameter here for future-proofing.

     * This allows named parameters to be used and allows contrib plugins to

     * make use of parameters in newer versions even if they don't exist in older versions.

     *

     * @param mixed ...$extra Extra arguments to allow for future versions of Moodle to add options without breaking plugins

     */

    public function __construct(

        mixed ...$extra,

    ) {

    }

    /**

     * Get the $ref for this class.

     *

     * @param bool $qualify Whether to qualify the reference with the #/components/ part.

     * @return string

     */

    public function get_reference(

        bool $qualify = true,

    ): string {

        return static::get_reference_for_class(

            classname: get_class($this),

            qualify: $qualify,

        );

    }

    /**

     * Get the OpenAPI data to include in the OpenAPI specification.

     *

     * @param specification $api

     * @param null|string $path

     * @return null|stdClass

     * @throws coding_exception

     */

    final public function get_openapi_schema(

        specification $api,

        ?string $path = null,

    ): ?stdClass {

        if (is_a($this, referenced_object::class)) {

            // This class is a referenced object, so we need to add it to the specification.

            if (!$api->is_reference_defined($this->get_reference())) {

                $api->add_component($this);

            }

            return (object) [

                '$ref' => $this->get_reference(),

            ];

        }

        return $this->get_openapi_description(

            api: $api,

            path: $path,

        );

    }

    /**

     * Get the OpenAPI data to include in the OpenAPI specification.

     *

     * @param specification $api

     * @param null|string $path

     * @return null|stdClass

     */

    abstract public function get_openapi_description(

        specification $api,

        ?string $path = null,

    ): ?stdClass;

    /**

     * Get the $ref a class name.

     *

     * https://swagger.io/docs/specification/using-ref/

     *

     * @param string $classname The class to get a reference for

     * @param bool $qualify Whether to qualify the reference with the #/components/ part

     * @return string The reference

     * @throws coding_exception

     */

    public static function get_reference_for_class(

        string $classname,

        bool $qualify = true,

    ): string {

        $reference = static::escape_reference($classname);

        if (!$qualify) {

            return $reference;

        }

        // Note: The following list must be kept in-sync with specification::add_component().

        return match (true) {

            is_a($classname, header_object::class, true) => static::get_reference_for_header($reference),

            is_a($classname, parameter::class, true) => static::get_reference_for_parameter($reference),

            is_a($classname, response::class, true) => static::get_reference_for_response($reference),

            is_a($classname, example::class, true) => static::get_reference_for_example($reference),

            is_a($classname, request_body::class, true) => static::get_reference_for_request_body($reference),

            is_a($classname, type_base::class, true) => static::get_reference_for_schema($reference),

            default => throw new coding_exception("Class {$classname} is not a schema."),

        };

    }

    /**

     * Get the qualified $ref for a parameter.

     *

     * @param string $reference

     * @return string

     */

    public static function get_reference_for_header(string $reference): string {

        return "#/components/headers/{$reference}";

    }

    /**

     * Get the qualified $ref for a parameter.

     *

     * @param string $reference

     * @return string

     */

    public static function get_reference_for_parameter(string $reference): string {

        return "#/components/parameters/{$reference}";

    }

    /**

     * Get the qualified $ref for a response.

     *

     * @param string $reference

     * @return string

     */

    public static function get_reference_for_response(string $reference): string {

        return "#/components/responses/{$reference}";

    }

    /**

     * Get the qualified $ref for an example.

     *

     * @param string $reference

     * @return string

     */

    public static function get_reference_for_example(string $reference): string {

        return "#/components/examples/{$reference}";

    }

    /**

     * Get the qualified $ref for a request body.

     *

     * @param string $reference

     * @return string

     */

    public static function get_reference_for_request_body(string $reference): string {

        return "#/components/requestBodies/{$reference}";

    }

    /**

     * Get the qualified $ref for a schema.

     *

     * @param string $reference

     * @return string

     */

    public static function get_reference_for_schema(string $reference): string {

        return "#/components/schemas/{$reference}";

    }

    /**

     * Escape a reference following rules defined at https://swagger.io/docs/specification/using-ref/.

     *

     * @param string $reference

     * @return string

     */

    public static function escape_reference(string $reference): string {

        // Note https://swagger.io/docs/specification/using-ref/ defines the following replacements:

        // ~ => ~0

        // / => ~1

        // We also add some other replacements:

        // \ => --

        // These must be used in all reference names.

        // See also https://spec.openapis.org/oas/v3.1.0#components-object

        // And the following regular expression:

        // ^[a-zA-Z0-9\.\-_]+$.

        return str_replace(

            ['~', '/', '\\'],

            ['~0', '~1', '--'],

            $reference,

        );

    }

    /**

     * Get the schema for a given type.

     *

     * @param param $type

     * @return stdClass

     */

    public function get_schema_from_type(param $type): stdClass {

        $data = new stdClass();

        $data->type = match ($type) {

            // OpenAPI uses an extension of the JSON Schema to define both integers and numbers (float).

            param::INT => 'integer',

            param::FLOAT => 'number',

            param::BOOL => 'boolean',

            // All other types are string types and most have a pattern.

            default => 'string',

        };

        if ($pattern = $type->get_clientside_expression()) {

            $data->pattern = $pattern;

        }

        return $data;

    }

}