x-. * * @var array */ public $x = Generator::UNDEFINED; /** * Arbitrary attachables for this annotation. * These will be ignored but can be used for custom processing. * * @var array */ public $attachables = Generator::UNDEFINED; public Context $_context; /** * Annotations that couldn't be merged by mapping or postprocessing. * * @var array */ public $_unmerged = []; /** * The properties which are required by [the spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md). * * @var list */ public static $_required = []; /** * Specify the type of the property. * * Examples: * 'name' => 'string' // a string * 'required' => 'boolean', // true or false * 'tags' => '[string]', // string array * 'in' => ["query", "header", "path", "formData", "body"] // must be one on these * 'oneOf' => [Schema::class] // array of schema objects. * * @var array> */ public static $_types = []; /** * Declarative mapping of Annotation types to properties. * * Examples: * Info::class => 'info', // Set @OA\Info annotation as the info property. * Parameter::class => ['parameters'], // Append @OA\Parameter annotations the parameters list. * PathItem::class => ['paths', 'path'], // Add @OA\PathItem annotation to the `paths` map and use `path` as key. * * @var array,string|array> */ public static $_nested = []; /** * Reverse mapping of $_nested with the allowed parent annotations. * * @var array> */ public static $_parents = []; /** * Properties that are blacklisted from the JSON output. * * @var array */ public static $_blacklist = ['_context', '_unmerged', '_analysis', 'attachables']; public function __construct(array $properties) { if (isset($properties['_context'])) { $this->_context = $properties['_context']; unset($properties['_context']); } elseif (Generator::$context) { $this->_context = Generator::$context; } else { $this->_context = new Context(['generated' => true]); } if ($this->_context->is('annotations') === false) { $this->_context->annotations = []; } $this->_context->annotations[] = $this; $nestedContext = new Context(['nested' => $this], $this->_context); foreach ($properties as $property => $value) { if (property_exists($this, $property)) { $this->{$property} = $value; if (is_array($value)) { foreach ($value as $key => $annotation) { if ($annotation instanceof AbstractAnnotation) { $this->{$property}[$key] = $this->nested($annotation, $nestedContext); } } } } elseif ($property !== 'value') { $this->{$property} = $value; } elseif (is_array($value)) { $annotations = []; foreach ($value as $annotation) { if ($annotation instanceof AbstractAnnotation) { $annotations[] = $annotation; } else { $this->_context->logger->warning('Unexpected field in ' . $this->identity() . ' in ' . $this->_context); } } $this->merge($annotations); } elseif (is_object($value)) { $this->merge([$value]); } else { if (!Generator::isDefault($value)) { $this->_context->logger->warning('Unexpected parameter "' . $property . '" in ' . $this->identity()); } } } } /** * Merge given annotations to their mapped properties configured in static::$_nested. * * Annotations that couldn't be merged are added to the _unmerged array. * * @param list $annotations * @param bool $ignore Ignore unmerged annotations * * @return list The unmerged annotations */ public function merge(array $annotations, bool $ignore = false): array { $unmerged = []; $nestedContext = new Context(['nested' => $this], $this->_context); foreach ($annotations as $annotation) { $mapped = false; if ($details = $this->matchNested($annotation)) { $property = $details->value; if (is_array($property)) { $property = $property[0]; if (Generator::isDefault($this->{$property})) { $this->{$property} = []; } $this->{$property}[] = $this->nested($annotation, $nestedContext); $mapped = true; } elseif (Generator::isDefault($this->{$property})) { // ignore duplicate nested if only one expected $this->{$property} = $this->nested($annotation, $nestedContext); $mapped = true; } } if (!$mapped) { $unmerged[] = $annotation; } } if (!$ignore) { foreach ($unmerged as $annotation) { $this->_unmerged[] = $this->nested($annotation, $nestedContext); } } return $unmerged; } /** * Merge the properties from the given object into this annotation. * Prevents overwriting properties that are already configured. * * @param object $object */ public function mergeProperties($object): void { $currentValues = get_object_vars($this); foreach ($object as $property => $value) { if ($property === '_context') { continue; } if (Generator::isDefault($currentValues[$property])) { // Overwrite default values $this->{$property} = $value; continue; } if ($property === '_unmerged') { $this->_unmerged = array_merge($this->_unmerged, $value); continue; } if ($currentValues[$property] !== $value) { // New value is not the same? if (Generator::isDefault($value)) { continue; } $identity = method_exists($object, 'identity') ? $object->identity() : $object::class; $context1 = $this->_context; $context2 = property_exists($object, '_context') ? $object->_context : 'unknown'; if ($this->{$property} instanceof AbstractAnnotation) { $context1 = $this->{$property}->_context; } $this->_context->logger->error('Multiple definitions for ' . $identity . '->' . $property . "\n Using: " . $context1 . "\n Skipping: " . $context2); } } } /** * Generate the documentation in YAML format. * * @param int-mask-of|null $flags A bit field of PARSE_* constants to customize the YAML parser behavior */ public function toYaml(?int $flags = null): string { if ($flags === null) { $flags = Yaml::DUMP_OBJECT_AS_MAP ^ Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE; } return Yaml::dump(json_decode($this->toJson(JSON_INVALID_UTF8_IGNORE)), 10, 2, $flags); } /** * Generate the documentation in JSON format. */ public function toJson(?int $flags = null): string { if ($flags === null) { $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_IGNORE; } return json_encode($this, $flags); } public function __debugInfo() { $properties = []; foreach (get_object_vars($this) as $property => $value) { if (!Generator::isDefault($value)) { $properties[$property] = $value; } } return $properties; } public function jsonSerialize(): \stdClass { $data = new \stdClass(); // Strip undefined values. foreach (get_object_vars($this) as $property => $value) { if (!Generator::isDefault($value)) { $data->{$property} = $value; } } // Strip properties that are for internal (swagger-php) use. foreach (static::$_blacklist as $property) { unset($data->{$property}); } // Correct empty array to empty objects. foreach (static::$_types as $property => $type) { if ($type === 'object' && is_array($data->{$property}) && $data->{$property} === []) { $data->{$property} = new \stdClass(); } } // Inject vendor properties. unset($data->x); if (is_array($this->x)) { foreach ($this->x as $property => $value) { $prefixed = 'x-' . $property; $data->{$prefixed} = $value; } } // Map nested keys foreach (static::$_nested as $nested) { if (is_string($nested) || count($nested) === 1) { continue; } $property = $nested[0]; if (Generator::isDefault($this->{$property})) { continue; } $keyField = $nested[1]; $object = new \stdClass(); foreach ($this->{$property} as $key => $item) { if (is_numeric($key) === false && is_array($item)) { $object->{$key} = $item; } else { $key = $item->{$keyField} ?? Generator::UNDEFINED; if (!Generator::isDefault($key) && empty($object->{$key})) { $object->{$key} = $item instanceof \JsonSerializable ? $item->jsonSerialize() : $item; unset($object->{$key}->{$keyField}); } } } $data->{$property} = $object; } // $ref if (isset($data->ref)) { // Only specific https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.1.0.md#reference-object $ref = ['$ref' => $data->ref]; if (!$this->_context->isVersion('3.0.x')) { foreach (['summary', 'description'] as $prop) { if (property_exists($data, $prop)) { $ref[$prop] = $data->{$prop}; } } } if (property_exists($this, 'nullable') && $this->nullable === true) { $ref = ['oneOf' => [$ref]]; if (!$this->_context->isVersion('3.0.x')) { $ref['oneOf'][] = ['type' => 'null']; } else { $ref['nullable'] = $data->nullable; } unset($data->ref, $data->nullable); // preserve other properties foreach (get_object_vars($data) as $property => $value) { $ref[$property] = $value; } } $data = (object) $ref; } if ($this->_context->isVersion('3.0.x')) { if (isset($data->exclusiveMinimum) && is_numeric($data->exclusiveMinimum)) { $data->minimum = $data->exclusiveMinimum; $data->exclusiveMinimum = true; } if (isset($data->exclusiveMaximum) && is_numeric($data->exclusiveMaximum)) { $data->maximum = $data->exclusiveMaximum; $data->exclusiveMaximum = true; } if (isset($data->type) && is_array($data->type)) { if (in_array('null', $data->type)) { $data->nullable = true; $data->type = array_filter($data->type, static fn ($v): bool => $v !== 'null'); if (1 === count($data->type)) { $data->type = array_pop($data->type); } } } if (isset($data->type) && is_array($data->type)) { if (1 === count($data->type)) { $data->type = array_pop($data->type); } else { unset($data->type); } } unset($data->unevaluatedProperties); } if (!$this->_context->isVersion('3.0.x')) { if (isset($data->nullable)) { if (true === $data->nullable) { if (isset($data->oneOf)) { $data->oneOf[] = ['type' => 'null']; } elseif (isset($data->anyOf)) { $data->anyOf[] = ['type' => 'null']; } elseif (isset($data->allOf)) { $data->allOf[] = ['type' => 'null']; } elseif (isset($data->type)) { $data->type = (array) $data->type; $data->type[] = 'null'; } } unset($data->nullable); } if (isset($data->minimum) && isset($data->exclusiveMinimum)) { if (true === $data->exclusiveMinimum) { $data->exclusiveMinimum = $data->minimum; unset($data->minimum); } elseif (false === $data->exclusiveMinimum) { unset($data->exclusiveMinimum); } } if (isset($data->maximum) && isset($data->exclusiveMaximum)) { if (true === $data->exclusiveMaximum) { $data->exclusiveMaximum = $data->maximum; unset($data->maximum); } elseif (false === $data->exclusiveMaximum) { unset($data->exclusiveMaximum); } } } return $data; } /** * Validate a given value against a `_$type` definition. */ private function validateValueType(string $type, mixed $value): bool { if (str_starts_with($type, '[') && str_ends_with($type, ']')) { // $value must be an array if (!$this->validateValueType('array', $value)) { return false; } $itemType = substr($type, 1, -1); foreach ($value as $item) { if (!$this->validateValueType($itemType, $item)) { return false; } } return true; } if (is_subclass_of($type, AbstractAnnotation::class)) { $type = 'object'; } $isValidType = fn (string $type, mixed $value): bool => match ($type) { 'string' => is_string($value), 'boolean' => is_bool($value), 'integer' => is_int($value), 'number' => is_numeric($value), 'object' => is_object($value), 'array' => is_array($value) && array_is_list($value), 'scheme' => in_array($value, ['http', 'https', 'ws', 'wss'], strict: true), default => throw new OpenApiException('Invalid type "' . $type . '"'), }; foreach (explode('|', $type) as $tt) { if ($isValidType(trim($tt), $value)) { return true; } } return false; } public function validate(?Analysis $analysis = null, string $version = OpenApi::DEFAULT_VERSION, ?object $context = null): bool { $isValid = true; // validate unmerged foreach ($this->_unmerged as $annotation) { if (!is_object($annotation)) { $this->_context->logger->warning('Unexpected type: "' . gettype($annotation) . '" in ' . $this->identity() . '->_unmerged, expecting a Annotation object'); break; } if ($details = $this->matchNested($annotation)) { $property = $details->value; if (is_array($property)) { $this->_context->logger->warning('Only one ' . $annotation->identity([]) . ' allowed for ' . $this->identity() . ' multiple found, skipped: ' . $annotation->_context); } else { $this->_context->logger->warning('Only one ' . $annotation->identity([]) . ' allowed for ' . $this->identity() . " multiple found in:\n Using: " . $this->{$property}->_context . "\n Skipped: " . $annotation->_context); } } elseif ($annotation instanceof AbstractAnnotation) { $message = 'Unexpected ' . $annotation->identity(); if ($annotation::$_parents) { $message .= ', expected to be inside ' . implode(', ', AbstractAnnotation::shorten($annotation::$_parents)); } $this->_context->logger->warning($message . ' in ' . $annotation->_context); } $isValid = false; } // validate conflicting keys foreach ($this::$_nested as $annotationClass => $nested) { if (is_string($nested) || count($nested) === 1) { continue; } $property = $nested[0]; if (Generator::isDefault($this->{$property})) { continue; } $keys = []; $keyField = $nested[1]; /** @var AbstractAnnotation $item */ foreach ($this->{$property} as $key => $item) { if (is_array($item) && !is_numeric($key)) { $this->_context->logger->warning($this->identity() . '->' . $property . ' is an object literal, use nested ' . AbstractAnnotation::shorten($annotationClass) . '() annotation(s) in ' . $this->_context); $keys[$key] = $item; } elseif (Generator::isDefault($item->{$keyField} ?? Generator::UNDEFINED)) { $this->_context->logger->error($item->identity() . ' is missing key-field: "' . $keyField . '" in ' . $item->_context); } elseif (isset($keys[$item->{$keyField}])) { $this->_context->logger->error('Multiple ' . $item->identity([]) . ' with the same ' . $keyField . '="' . $item->{$keyField} . "\":\n " . $item->_context . "\n " . $keys[$item->{$keyField}]->_context); } else { $keys[$item->{$keyField}] = $item; } } } // validate refs if ($analysis?->openapi && property_exists($this, 'ref') && !Generator::isDefault($this->ref) && is_string($this->ref)) { if (str_starts_with($this->ref, '#/')) { try { $analysis->openapi->ref($this->ref); } catch (\Exception $e) { $this->_context->logger->warning($e->getMessage() . ' for ' . $this->identity() . ' in ' . $this->_context, ['exception' => $e]); $isValid = false; } } } // validate required properties if (!property_exists($this, 'ref') || Generator::isDefault($this->ref) || !is_string($this->ref)) { foreach ($this::$_required as $property) { if (Generator::isDefault($this->{$property})) { $message = 'Missing required field "' . $property . '" for ' . $this->identity() . ' in ' . $this->_context; foreach ($this::$_nested as $class => $nested) { $nestedProperty = is_array($nested) ? $nested[0] : $nested; if ($property === $nestedProperty) { if ($this instanceof OpenApi) { $message = 'Required ' . AbstractAnnotation::shorten($class) . '() not found'; } elseif (is_array($nested)) { $message = $this->identity() . ' requires at least one ' . AbstractAnnotation::shorten($class) . '() in ' . $this->_context; } else { $message = $this->identity() . ' requires a ' . AbstractAnnotation::shorten($class) . '() in ' . $this->_context; } break; } } $this->_context->logger->warning($message); } } } // validate types foreach ($this::$_types as $property => $type) { $value = $this->{$property}; if (Generator::isDefault($value) || $value === null) { continue; } if (is_string($type)) { if (!$this->validateValueType($type, $value)) { $this->_context->logger->warning($this->identity() . '->' . $property . ' is a "' . gettype($value) . '", expecting a "' . $type . '" in ' . $this->_context); $isValid = false; } } elseif (is_array($type)) { // enum? if (!in_array($value, $type)) { $this->_context->logger->warning($this->identity() . '->' . $property . ' "' . $value . '" is invalid, expecting "' . implode('", "', $type) . '" in ' . $this->_context); } } else { throw new OpenApiException('Invalid ' . static::class . '::$_types[' . $property . ']'); } } // validate example/examples if (property_exists($this, 'example') && property_exists($this, 'examples')) { if (!Generator::isDefault($this->example) && !Generator::isDefault($this->examples)) { $this->_context->logger->warning($this->identity() . ': "example" and "examples" are mutually exclusive'); $isValid = false; } } return $isValid; } /** * Return a simple string representation of the annotation. * * @param array|null $properties the properties to include in the string representation * @example "@OA\Response(response=200)" */ public function identity(?array $properties = null): string { $class = static::class; if (null === $properties) { $properties = []; /** @var class-string $parent */ foreach (static::$_parents as $parent) { foreach ($parent::$_nested as $annotationClass => $entry) { if ($annotationClass === $class && is_array($entry) && !Generator::isDefault($this->{$entry[1]})) { $properties[] = $entry[1]; break 2; } } } } $details = []; foreach ($properties as $property) { $value = $this->{$property}; if ($value !== null && !Generator::isDefault($value)) { $details[] = $property . '=' . (is_string($value) ? '"' . $value . '"' : $value); } } return static::shorten(static::class) . '(' . implode(',', $details) . ')'; } /** * Check if $other can be nested, and if so, return details about where/how. * * @param AbstractAnnotation $other the other annotation * * @return null|object key/value object or null */ public function matchNested($other) { if ($other instanceof AbstractAnnotation && array_key_exists($root = $other->getRoot(), static::$_nested)) { return (object) ['key' => $root, 'value' => static::$_nested[$root]]; } return null; } /** * Get the root annotation. * * This is used for resolving type equality and nesting rules to allow those rules to also work for custom, * derived annotation classes. * * @return class-string the root annotation class in the OpenApi\\Annotations namespace */ public function getRoot(): string { $class = static::class; do { if (str_starts_with($class, 'OpenApi\\Annotations\\')) { break; } } while ($class = get_parent_class($class)); return $class; } /** * Match the annotation root. * * @param class-string $thisClass the root class to match */ public function isRoot(string $thisClass): bool { return static::class === $thisClass || $this->getRoot() === $thisClass; } /** * Wrap the context with a reference to the annotation it is nested in. */ protected function nested(AbstractAnnotation $annotation, Context $nestedContext): self { if (property_exists($annotation, '_context') && $annotation->_context === $this->_context) { $annotation->_context = $nestedContext; } return $annotation; } protected function combine(...$args): array { $combined = []; foreach ($args as $arg) { if (is_array($arg)) { $combined = array_merge($combined, $arg); } else { $combined[] = $arg; } } return array_filter($combined, static fn ($value): bool => !Generator::isDefault($value) && $value !== null); } /** * Shorten class name(s). * * @param array|object|string $classes Class(es) to shorten * * @return string|list One or more shortened class names */ protected static function shorten($classes) { $short = []; foreach ((array) $classes as $class) { $short[] = '@' . str_replace([ 'OpenApi\\Annotations\\', 'OpenApi\\Attributes\\', ], 'OA\\', (string) $class); } return is_array($classes) ? $short : array_pop($short); } }