Add API metadata attributes and command for coverage docs

Implemented API metadata attributes for service and method documentation. Added GenerateCoverageDocumentationCommand to generate API coverage documentation in Markdown format. This enhances maintainability and provides comprehensive API documentation automatically. Signed-off-by: mesilov <[email protected]>
mesilov · Aug 18, 2024 · ca24152 · ca24152
1 parent 9adf3a7
commit ca24152
Show file tree

Hide file tree

Showing 14 changed files with 647 additions and 54 deletions.
diff --git a/bin/console b/bin/console
@@ -1,8 +1,11 @@
 #!/usr/bin/env php
 <?php
 
+use Bitrix24\SDK\Attributes\Services\AttributesParser;
+use Bitrix24\SDK\Services\ServiceBuilderFactory;
 use Bitrix24\SDK\Tools\Commands\CopyPropertyValues;
 use Bitrix24\SDK\Tools\Commands\GenerateContactsCommand;
+use Bitrix24\SDK\Infrastructure\Console\Commands;
 use Bitrix24\SDK\Tools\Commands\PerformanceBenchmarks\ListCommand;
 use Bitrix24\SDK\Tools\Commands\ShowFieldsDescriptionCommand;
 use Monolog\Handler\StreamHandler;
@@ -12,6 +15,8 @@ use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Input\ArgvInput;
 use Symfony\Component\Dotenv\Dotenv;
 use Symfony\Component\ErrorHandler\Debug;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+use Typhoon\Reflection\TyphoonReflector;
 
 if (!in_array(PHP_SAPI, ['cli', 'phpdbg', 'embed'], true)) {
     echo 'Warning: The console should be invoked via the CLI version of PHP, not the ' . PHP_SAPI . ' SAPI' . PHP_EOL;
@@ -55,4 +60,10 @@ $application->add(new GenerateContactsCommand($log));
 $application->add(new ListCommand($log));
 $application->add(new ShowFieldsDescriptionCommand($log));
 $application->add(new CopyPropertyValues($log));
+$application->add(new Commands\GenerateCoverageDocumentationCommand(
+    new AttributesParser(TyphoonReflector::build(), new Symfony\Component\Filesystem\Filesystem()),
+    new ServiceBuilderFactory(new EventDispatcher(), $log),
+    new Symfony\Component\Finder\Finder(),
+    new Symfony\Component\Filesystem\Filesystem(),
+    $log));
 $application->run($input);
diff --git a/docs/EN/Services/bitrix24-php-sdk-methods.md b/docs/EN/Services/bitrix24-php-sdk-methods.md
@@ -0,0 +1,20 @@
+## All bitrix24-php-sdk methods
+
+| **Scope** | **API method with documentation**      | **Description**  | Method in SDK  |
+|-----------|----------------------------------------|------------------|----------------|
+|`catalog`|[catalog.catalog.get](https://training.bitrix24.com/rest_help/catalog/catalog/catalog_catalog_get.php)|The method gets field values of commercial catalog by ID.|[`Bitrix24\SDK\Services\Catalog\Catalog\Service\Catalog::get`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Catalog/Service/Catalog.php#L34-L37)<br/>Return type<br/>[`Bitrix24\SDK\Services\Catalog\Catalog\Result\CatalogResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Catalog/Result/CatalogResult.php)|
+|`catalog`|[catalog.catalog.list](https://training.bitrix24.com/rest_help/catalog/catalog/catalog_catalog_list.php)|The method gets field value of commercial catalog product list|[`Bitrix24\SDK\Services\Catalog\Catalog\Service\Catalog::list`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Catalog/Service/Catalog.php#L56-L64)<br/>Return type<br/>[`Bitrix24\SDK\Services\Catalog\Catalog\Result\CatalogsResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Catalog/Result/CatalogsResult.php)|
+|`catalog`|[catalog.catalog.getFields](https://training.bitrix24.com/rest_help/catalog/catalog/catalog_catalog_getfields.php)|Retrieves the fields for the catalog.|[`Bitrix24\SDK\Services\Catalog\Catalog\Service\Catalog::fields`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Catalog/Service/Catalog.php#L79-L82)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\FieldsResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/FieldsResult.php)|
+|`catalog`|[catalog.product.get](https://training.bitrix24.com/rest_help/catalog/product/catalog_product_get.php)|The method gets field value of commercial catalog product by ID.|[`Bitrix24\SDK\Services\Catalog\Product\Service\Product::get`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Service/Product.php#L49-L52)<br/>Return type<br/>[`Bitrix24\SDK\Services\Catalog\Product\Result\ProductResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Result/ProductResult.php)|
+|`catalog`|[catalog.product.add](https://training.bitrix24.com/rest_help/catalog/product/catalog_product_add.php)|The method adds a commercial catalog product.|[`Bitrix24\SDK\Services\Catalog\Product\Service\Product::add`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Service/Product.php#L68-L74)<br/>Return type<br/>[`Bitrix24\SDK\Services\Catalog\Product\Result\ProductResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Result/ProductResult.php)|
+|`catalog`|[catalog.product.delete](https://training.bitrix24.com/rest_help/catalog/product/catalog_product_delete.php)|The method deletes commercial catalog product by ID|[`Bitrix24\SDK\Services\Catalog\Product\Service\Product::delete`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Service/Product.php#L90-L93)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\DeletedItemResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/DeletedItemResult.php)|
+|`catalog`|[catalog.product.list](https://training.bitrix24.com/rest_help/catalog/product/catalog_product_list.php)|The method gets list of commercial catalog products by filter.|[`Bitrix24\SDK\Services\Catalog\Product\Service\Product::list`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Service/Product.php#L107-L115)<br/>Return type<br/>[`Bitrix24\SDK\Services\Catalog\Product\Result\ProductsResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Result/ProductsResult.php)|
+|`catalog`|[catalog.product.getFieldsByFilter](https://training.bitrix24.com/rest_help/catalog/product/catalog_product_getfieldsbyfilter.php)|The method returns commercial catalog product fields by filter.|[`Bitrix24\SDK\Services\Catalog\Product\Service\Product::fieldsByFilter`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/Catalog/Product/Service/Product.php#L133-L144)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\FieldsResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/FieldsResult.php)|
+|`crm`|[crm.deal.add](https://training.bitrix24.com/rest_help/crm/deals/crm_deal_add.php)|Add new deal|[`Bitrix24\SDK\Services\CRM\Deal\Service\Deal::add`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Deal/Service/Deal.php#L96-L107)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\AddedItemResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/AddedItemResult.php)|
+|`crm`|[crm.deal.delete](https://training.bitrix24.com/rest_help/crm/deals/crm_deal_delete.php)|Delete deal|[`Bitrix24\SDK\Services\CRM\Deal\Service\Deal::delete`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Deal/Service/Deal.php#L125-L135)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\DeletedItemResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/DeletedItemResult.php)|
+|`crm`|[crm.activity.add](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_add.php)|Creates and adds a new activity.|[`Bitrix24\SDK\Services\CRM\Activity\Service\Activity::add`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Service/Activity.php#L101-L111)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\AddedItemResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/AddedItemResult.php)<br/><br/>⚡️Batch methods: <br/><ul><li>`Bitrix24\SDK\Services\CRM\Activity\Service\Batch::add`<br/>Return type: `Generator<int<1, max>, Bitrix24\SDK\Core\Result\AddedItemBatchResult, mixed, mixed>`</li></ul>|
+|`crm`|[crm.activity.delete](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_delete.php)|Deletes the specified activity and all the associated objects.|[`Bitrix24\SDK\Services\CRM\Activity\Service\Activity::delete`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Service/Activity.php#L129-L139)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\DeletedItemResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/DeletedItemResult.php)<br/><br/>⚡️Batch methods: <br/><ul><li>`Bitrix24\SDK\Services\CRM\Activity\Service\Batch::delete`<br/>Return type: `Generator<int<1, max>, Bitrix24\SDK\Core\Result\DeletedItemBatchResult, mixed, mixed>`</li></ul>|
+|`crm`|[crm.activity.fields](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_fields.php)|Returns the description of activity fields|[`Bitrix24\SDK\Services\CRM\Activity\Service\Activity::fields`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Service/Activity.php#L155-L158)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\FieldsResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/FieldsResult.php)|
+|`crm`|[crm.activity.get](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_get.php)|Returns activity by the specified activity ID|[`Bitrix24\SDK\Services\CRM\Activity\Service\Activity::get`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Service/Activity.php#L176-L186)<br/>Return type<br/>[`Bitrix24\SDK\Services\CRM\Activity\Result\ActivityResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Result/ActivityResult.php)|
+|`crm`|[crm.activity.list](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_list.php)|Returns a list of activity selected by the filter specified as the parameter. See the example for the filter notation.|[`Bitrix24\SDK\Services\CRM\Activity\Service\Activity::list`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Service/Activity.php#L297-L310)<br/>Return type<br/>[`Bitrix24\SDK\Services\CRM\Activity\Result\ActivitiesResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Result/ActivitiesResult.php)<br/><br/>⚡️Batch methods: <br/><ul><li>`Bitrix24\SDK\Services\CRM\Activity\ReadModel\EmailFetcher::getList`<br/>Return type: `Generator<int<1, max>, Bitrix24\SDK\Services\CRM\Activity\Result\Email\EmailActivityItemResult, mixed, mixed>`</li><li>`Bitrix24\SDK\Services\CRM\Activity\Service\Batch::list`<br/>Return type: `Generator<int<1, max>, Bitrix24\SDK\Services\CRM\Activity\Result\ActivityItemResult, mixed, mixed>`</li></ul>|
+|`crm`|[crm.activity.update](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_update.php)|Updates the specified (existing) activity.|[`Bitrix24\SDK\Services\CRM\Activity\Service\Activity::update`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Services/CRM/Activity/Service/Activity.php#L373-L384)<br/>Return type<br/>[`Bitrix24\SDK\Core\Result\UpdatedItemResult`](https://github.com/mesilov/bitrix24-php-sdk/blob/feature/390-prepare-publish-2-0/src/Core/Result/UpdatedItemResult.php)|
diff --git a/src/Attributes/ApiBatchMethodMetadata.php b/src/Attributes/ApiBatchMethodMetadata.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class ApiBatchMethodMetadata
+{
+    public function __construct(
+        public string  $name,
+        public string  $documentationUrl,
+        public ?string $description = null,
+        public bool    $isDeprecated = false,
+        public ?string $deprecationMessage = null
+    )
+    {
+    }
+}
diff --git a/src/Attributes/ApiBatchServiceMetadata.php b/src/Attributes/ApiBatchServiceMetadata.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Attributes;
+
+use Attribute;
+use Bitrix24\SDK\Core\Credentials\Scope;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class ApiBatchServiceMetadata
+{
+    public function __construct(
+        public Scope   $scope,
+        public ?string $documentationUrl = null,
+        public ?string $description = null,
+        public bool    $isDeprecated = false,
+        public ?string $deprecationMessage = null
+    )
+    {
+    }
+}
diff --git a/src/Attributes/ApiEndpointMetadata.php b/src/Attributes/ApiEndpointMetadata.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class ApiEndpointMetadata
+{
+    public function __construct(
+        public string  $name,
+        public string  $documentationUrl,
+        public ?string $description = null,
+        public bool    $isDeprecated = false,
+        public ?string $deprecationMessage = null
+    )
+    {
+    }
+}
diff --git a/src/Attributes/ApiServiceMetadata.php b/src/Attributes/ApiServiceMetadata.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Attributes;
+
+use Attribute;
+use Bitrix24\SDK\Core\Credentials\Scope;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class ApiServiceMetadata
+{
+    public function __construct(
+        public Scope   $scope,
+        public ?string $documentationUrl = null,
+        public ?string $description = null,
+        public bool    $isDeprecated = false,
+        public ?string $deprecationMessage = null
+    )
+    {
+    }
+}
diff --git a/src/Attributes/Services/AttributesParser.php b/src/Attributes/Services/AttributesParser.php
@@ -0,0 +1,139 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Attributes\Services;
+
+
+use Bitrix24\SDK\Attributes\ApiBatchMethodMetadata;
+use Bitrix24\SDK\Attributes\ApiBatchServiceMetadata;
+use Bitrix24\SDK\Attributes\ApiEndpointMetadata;
+use Bitrix24\SDK\Attributes\ApiServiceMetadata;
+use ReflectionClass;
+use Symfony\Component\Filesystem\Filesystem;
+use Typhoon\Reflection\TyphoonReflector;
+use function Typhoon\Type\stringify;
+
+readonly class AttributesParser
+{
+    public function __construct(
+        private TyphoonReflector $typhoonReflector,
+        private Filesystem       $filesystem,
+    )
+    {
+    }
+
+    /**
+     * @param class-string[] $sdkClassNames
+     * @return array<string, mixed>
+     */
+    public function getSupportedInSdkApiMethods(array $sdkClassNames, string $sdkBaseDir): array
+    {
+        $supportedInSdkMethods = [];
+        foreach ($sdkClassNames as $className) {
+            $reflectionServiceClass = new ReflectionClass($className);
+            $apiServiceAttribute = $reflectionServiceClass->getAttributes(ApiServiceMetadata::class);
+            if ($apiServiceAttribute === []) {
+                continue;
+            }
+            $apiServiceAttribute = $apiServiceAttribute[0];
+            /**
+             * @var ApiServiceMetadata $apiServiceAttrInstance
+             */
+            $apiServiceAttrInstance = $apiServiceAttribute->newInstance();
+            // process api service
+            $serviceMethods = $reflectionServiceClass->getMethods();
+            foreach ($serviceMethods as $method) {
+                $attributes = $method->getAttributes(ApiEndpointMetadata::class);
+                foreach ($attributes as $attribute) {
+                    /**
+                     * @var ApiEndpointMetadata $instance
+                     */
+                    $instance = $attribute->newInstance();
+
+                    // find return type file name
+                    $returnTypeFileName = null;
+                    if ($method->getReturnType() !== null) {
+                        $returnTypeName = $method->getReturnType()->getName();
+                        if (class_exists($returnTypeName)) {
+                            $reflectionReturnType = new ReflectionClass($returnTypeName);
+                            $returnTypeFileName = substr($this->filesystem->makePathRelative($reflectionReturnType->getFileName(), $sdkBaseDir), 0, -1);
+                        }
+                    }
+
+                    $supportedInSdkMethods[$instance->name] = [
+                        'sdk_scope' => $apiServiceAttrInstance->scope->getScopeCodes()[0],
+                        'name' => $instance->name,
+                        'documentation_url' => $instance->documentationUrl,
+                        'description' => $instance->description,
+                        'is_deprecated' => $instance->isDeprecated,
+                        'deprecation_message' => $instance->deprecationMessage,
+                        'sdk_method_name' => $method->getName(),
+                        'sdk_method_file_name' => substr($this->filesystem->makePathRelative($method->getFileName(), $sdkBaseDir), 0, -1),
+                        'sdk_method_file_start_line' => $method->getStartLine(),
+                        'sdk_method_file_end_line' => $method->getEndLine(),
+                        'sdk_class_name' => $className,
+                        'sdk_return_type_class' => $method->getReturnType()?->getName(),
+                        'sdk_return_type_file_name' => $returnTypeFileName
+                    ];
+                }
+            }
+        }
+        return $supportedInSdkMethods;
+    }
+
+    /**
+     * @param class-string[] $sdkClassNames
+     * @return array<string, mixed>
+     */
+    public function getSupportedInSdkBatchMethods(array $sdkClassNames): array
+    {
+        $supportedInSdkMethods = [];
+        foreach ($sdkClassNames as $className) {
+            $reflectionServiceClass = new ReflectionClass($className);
+            $apiServiceAttribute = $reflectionServiceClass->getAttributes(ApiBatchServiceMetadata::class);
+            if ($apiServiceAttribute === []) {
+                continue;
+            }
+            //try to get type information from phpdoc annotations
+            $typhoonClassMeta = $this->typhoonReflector->reflectClass($className);
+            /**
+             * @var ApiBatchServiceMetadata $apiServiceAttrInstance
+             */
+            $apiServiceAttribute = $apiServiceAttribute[0];
+            $apiServiceAttrInstance = $apiServiceAttribute->newInstance();
+            // process api service
+            $serviceMethods = $reflectionServiceClass->getMethods();
+            foreach ($serviceMethods as $method) {
+                $attributes = $method->getAttributes(ApiBatchMethodMetadata::class);
+                foreach ($attributes as $attribute) {
+                    /**
+                     * @var ApiBatchMethodMetadata $instance
+                     */
+                    $instance = $attribute->newInstance();
+                    $sdkReturnTypeTyphoon = null;
+                    if ($method->getReturnType() !== null) {
+                        // get return type from phpdoc annotation
+                        $sdkReturnTypeTyphoon = stringify($typhoonClassMeta->methods()[$method->getName()]->returnType());
+                    }
+
+                    $supportedInSdkMethods[$instance->name][] = [
+                        'sdk_scope' => $apiServiceAttrInstance->scope->getScopeCodes()[0],
+                        'name' => $instance->name,
+                        'documentation_url' => $instance->documentationUrl,
+                        'description' => $instance->description,
+                        'is_deprecated' => $instance->isDeprecated,
+                        'deprecation_message' => $instance->deprecationMessage,
+                        'sdk_method_name' => $method->getName(),
+                        'sdk_method_file_name' => $method->getFileName(),
+                        'sdk_method_file_start_line' => $method->getStartLine(),
+                        'sdk_method_file_end_line' => $method->getEndLine(),
+                        'sdk_method_return_type_typhoon' => $sdkReturnTypeTyphoon,
+                        'sdk_class_name' => $className,
+                    ];
+                }
+            }
+        }
+        return $supportedInSdkMethods;
+    }
+}