AutorÃa | Ultima modificación | Ver Log |
<?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;}}