mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-06-24 18:58:46 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added an possibilty to document "virtual" properties to api documentation, which are added dynamically during the normalization priocess

Browse source
This commit is contained in:
Jan Böhmer 2023-10-02 00:21:59 +02:00
parent 90518056cd
commit 607bb45f5f
2 changed files with 209 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

142
src/ApiPlatform/AddDocumentedAPIPropertiesJSONSchemaFactory.php Normal file
View file

@ -0,0 +1,142 @@
<?php
/*
* This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
*
* Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
namespace App\ApiPlatform;
use ApiPlatform\JsonSchema\Schema;
use ApiPlatform\JsonSchema\SchemaFactoryInterface;
use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\Operation;
use App\Entity\Attachments\Attachment;
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\PropertyInfo\Type;
/**
* This decorator adds the properties given by DocumentedAPIProperty attributes on the classes to the schema.
*/
#[AsDecorator('api_platform.json_schema.schema_factory')]
class AddDocumentedAPIPropertiesJSONSchemaFactory implements SchemaFactoryInterface
{
public function __construct(private readonly SchemaFactoryInterface $decorated)
{
}
public function buildSchema(
string $className,
string $format = 'json',
string $type = Schema::TYPE_OUTPUT,
Operation $operation = null,
Schema $schema = null,
array $serializerContext = null,
bool $forceCollection = false
): Schema {
$schema = $this->decorated->buildSchema($className, $format, $type, $operation, $schema, $serializerContext, $forceCollection);
//Check if there is are DocumentedAPIProperty attributes on the class
$reflectionClass = new \ReflectionClass($className);
$attributes = $reflectionClass->getAttributes(DocumentedAPIProperty::class);
foreach ($attributes as $attribute) {
/** @var DocumentedAPIProperty $api_property */
$api_property = $attribute->newInstance();
$this->addPropertyToSchema($schema, $api_property->schemaName, $api_property->property,
$api_property, $serializerContext ?? [], $format);
}
/*if ($className === Attachment::class) {
$api_property = new ApiProperty(description: 'Test');
$this->buildPropertySchema($schema, 'Attachment-Read', 'media_url', $api_property, $serializerContext ?? [],
$format);
}*/
//Add media_url and thumbnail_url to the Attachment schema
/*if ($className === Attachment::class) {
$tmp = $schema->getDefinitions()->getArrayCopy();
$tmp['properties']['media_url'] = [
'type' => 'string',
'readOnly' => true,
'format' => 'uri',
'description' => 'The URL to the attachment',
];
$tmp['properties']['thumbnail_url'] = [
'type' => 'string',
'readOnly' => true,
'format' => 'uri',
'description' => 'The URL to the thumbnail of the attachment',
];
$schema->setDefinitions(new \ArrayObject($tmp));
}*/
//Fd
return $schema;
}
private function addPropertyToSchema(Schema $schema, string $definitionName, string $normalizedPropertyName, DocumentedAPIProperty $propertyMetadata, array $serializerContext, string $format): void
{
$version = $schema->getVersion();
$swagger = Schema::VERSION_SWAGGER === $version;
if (false === $propertyMetadata->writeable) {
$propertySchema['readOnly'] = true;
}
if (!$swagger && false === $propertyMetadata->readable) {
$propertySchema['writeOnly'] = true;
}
if (null !== $description = $propertyMetadata->description) {
$propertySchema['description'] = $description;
}
$deprecationReason = $propertyMetadata->deprecationReason;
// see https://github.com/json-schema-org/json-schema-spec/pull/737
if (!$swagger && null !== $deprecationReason) {
$propertySchema['deprecated'] = true;
}
if (!isset($propertySchema['default']) && !empty($default = $propertyMetadata->default)) {
if ($default instanceof \BackedEnum) {
$default = $default->value;
}
$propertySchema['default'] = $default;
}
if (!isset($propertySchema['example']) && !empty($example = $propertyMetadata->example)) {
$propertySchema['example'] = $example;
}
if (!isset($propertySchema['example']) && isset($propertySchema['default'])) {
$propertySchema['example'] = $propertySchema['default'];
}
$propertySchema['type'] = $propertyMetadata->type;
$propertySchema['nullable'] = $propertyMetadata->nullable;
$propertySchema = new \ArrayObject($propertySchema);
$schema->getDefinitions()[$definitionName]['properties'][$normalizedPropertyName] = $propertySchema;
}
}

67
src/ApiPlatform/DocumentedAPIProperty.php Normal file
View file

@ -0,0 +1,67 @@
<?php
/*
* This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
*
* Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
namespace App\ApiPlatform;
/**
* When this attribute is applied to a class, an property will be added to the API documentation using the given parameters.
* This is useful for adding properties to the API documentation, that are not existing in the entity class itself,
* but get added by a normalizer.
*/
#[\Attribute(\Attribute::TARGET_CLASS| \Attribute::IS_REPEATABLE)]
final class DocumentedAPIProperty
{
public function __construct(
/**
* @param string $schemaName The name of the schema to add the property to (e.g. "Part-Read")
*/
public readonly string $schemaName,
/**
* @var string $property The name of the property to add to the schema
*/
public readonly string $property,
public readonly string $type = 'string',
public readonly bool $nullable = true,
/**
* @var string $description The description of the property
*/
public readonly ?string $description = null,
/**
* @var bool True if the property is readable, false otherwise
*/
public readonly bool $readable = true,
/**
* @var bool True if the property is writable, false otherwise
*/
public readonly bool $writeable = false,
/**
* @var string|null The deprecation reason of the property
*/
public readonly ?string $deprecationReason = null,
/** @var mixed The default value of this property */
public readonly mixed $default = null,
public readonly mixed $example = null,
)
{
}
}