Is there support for API docs generation of any package?

[FrankVisuals]

I tried to use https://scramble.dedoc.co/ to generate API docs for my actions. However, it does not seem to be able to detect the information as it does not use the "FormRequest" etc.

Is there any API docs generator package that is supported by laravel-actions? I found this package that intents to enable actions in scramble, but it's outdated and does not work with the latest version.

I played around and tried to implement it on my own, but failed.

[luchfirearmland]

Tried both Scramble and Scribe but failed. Omg. Converted all of my controllers to Laravel Actions. I'm doomed. I don't want to create API docs by hand. 🥹

[luchfirearmland]

It worked kinda with Scramble but the request body does not show on docs. This is making me sweat buckets. How am I gonna create an API docs quickly?

[luchfirearmland]

Have you succeeded with anything re docs generation, @FrankVisuals ?

[FrankVisuals]

@luchfirearmland I was working on an enhancement for scramble. To be honest, I do not fully understand how it is supposed to be build.

I've created this so far (copy with care) in app/Extensions/LaravelActionsExtension.php

<?php

namespace App\Extensions;

use Arr;
use Dedoc\Scramble\Infer\Reflector\ClassReflector;
use Dedoc\Scramble\Support\Generator\Combined\AnyOf;
use Dedoc\Scramble\Support\Generator\Operation;
use Dedoc\Scramble\Support\Generator\Parameter;
use Dedoc\Scramble\Support\Generator\Reference;
use Dedoc\Scramble\Support\Generator\RequestBodyObject;
use Dedoc\Scramble\Support\Generator\Response;
use Dedoc\Scramble\Support\Generator\Types as OpenApiTypes;
use Dedoc\Scramble\Support\Generator\Schema;
use Dedoc\Scramble\Support\OperationExtensions\RequestBodyExtension;
use Dedoc\Scramble\Support\OperationExtensions\RulesExtractor\GeneratesParametersFromRules;
use Dedoc\Scramble\Support\OperationExtensions\RulesExtractor\ParametersExtractionResult;
use Dedoc\Scramble\Support\PhpDoc;
use Dedoc\Scramble\Support\RouteInfo;
use Dedoc\Scramble\Support\SchemaClassDocReflector;
use Dedoc\Scramble\Support\Type\Union;
use Illuminate\Support\Collection;
use PhpParser\NodeFinder;
use PhpParser\Node;
use Illuminate\Support\Str;
use PhpParser\Comment\Doc;

class LaravelActionsExtension extends RequestBodyExtension
{
    use GeneratesParametersFromRules;

    public function handle(Operation $operation, RouteInfo $routeInfo)
    {
        if (
            $routeInfo->methodName() !== 'asController' ||
            $routeInfo->getMethodType()->name !== '__invoke'
        ) {
            return;
        }

        $this->addResponse($operation, $routeInfo);
        $this->addDescription($operation, $routeInfo);
        $this->addRules($operation, $routeInfo);
    }

    private function extractRules(string $action)
    {
        $reflection = new \ReflectionMethod(...explode('@', $action));
        $requestClassName = $reflection->class;
        $request = new $requestClassName();
        return $request->rules();
    }

    private function actionNode(
        string $action,
        mixed $rules,
        RouteInfo $routeInfo
    ) {
        $reflection = new \ReflectionMethod(...explode('@', $action));
        $requestClassName = $reflection->class;

        $classReflector = ClassReflector::make($requestClassName);
        $phpDocReflector = SchemaClassDocReflector::createFromDocString(
            $classReflector->getReflection()->getDocComment() ?: ''
        );

        $schemaName =
            ($phpDocReflector->getTagValue('@ignoreSchema')->value ?? null) !==
            null
                ? null
                : $phpDocReflector->getSchemaName($requestClassName);

        return new ParametersExtractionResult(
            parameters: $this->makeParameters(
                node: (new NodeFinder())->find(
                    Arr::wrap(
                        $classReflector->getMethod('rules')->getAstNode()->stmts
                    ),
                    fn(Node $node) => $node instanceof Node\Expr\ArrayItem &&
                        $node->key instanceof Node\Scalar\String_ &&
                        $node->getAttribute('parsedPhpDoc')
                ),
                rules: $rules,
                typeTransformer: $this->openApiTransformer,
                in: in_array(
                    mb_strtolower($routeInfo->route->methods()[0]),
                    RequestBodyExtension::HTTP_METHODS_WITHOUT_REQUEST_BODY
                )
                    ? 'query'
                    : 'body'
            ),
            schemaName: $schemaName,
            description: $phpDocReflector->getDescription()
        );
    }

    private function addRules(Operation $operation, RouteInfo $routeInfo)
    {
        $rules = [];

        $action = $routeInfo->route->getAction('uses');

        $rules = $this->extractRules($action);

        $rulesResults = $this->actionNode($action, $rules, $routeInfo);

        $mediaType = $this->getMediaType(
            $operation,
            $routeInfo,
            $rulesResults->parameters
        );

        if (empty($rulesResults->parameters)) {
            return;
        }

        if (
            in_array(
                $operation->method,
                static::HTTP_METHODS_WITHOUT_REQUEST_BODY
            )
        ) {
            $operation->addParameters(
                $this->convertDotNamedParamsToComplexStructures(
                    $rulesResults->parameters
                )
            );

            return;
        }

        [$nonBodyParams, $bodyParams] = collect($rulesResults->parameters)
            ->partition(
                fn(Parameter $p) => $p->in !== 'body' ||
                    $p->getAttribute('isInQuery') ||
                    $p->getAttribute('nonBody')
            )
            ->map->toArray();

        $operation->addParameters(
            $this->convertDotNamedParamsToComplexStructures($nonBodyParams)
        );

        if (!$bodyParams) {
            return;
        }
        [$schemaResults, $schemalessResults] = collect([
            $rulesResults,
        ])->partition('schemaName');
        $schemalessResults = collect([
            $this->mergeSchemalessRulesResults($schemalessResults->values()),
        ]);

        $schemas = $schemaResults
            ->merge($schemalessResults)
            ->map(function (ParametersExtractionResult $r) use (
                $nonBodyParams
            ) {
                $qpNames = collect($nonBodyParams)->keyBy(
                    fn($p) => "$p->name.$p->in"
                );

                $r->parameters = collect($r->parameters)
                    ->filter(fn($p) => !$qpNames->has("$p->name.$p->in"))
                    ->values()
                    ->all();

                return $r;
            })
            ->filter(
                fn(ParametersExtractionResult $r) => count($r->parameters) ||
                    $r->schemaName
            )
            ->map($this->makeSchemaFromResults(...));

        if ($schemas->isEmpty()) {
            return;
        }

        $schema = $this->makeComposedRequestBodySchema($schemas);
        if (!$schema instanceof Reference) {
            $schema = Schema::fromType($schema);
        }

        $operation->addRequestBodyObject(
            RequestBodyObject::make()
                ->setContent($mediaType, $schema)
                ->required($this->isSchemaRequired($schema))
        );
    }

    private function addDescription(Operation $operation, RouteInfo $routeInfo)
    {
        $reflection = new \ReflectionMethod(
            ...explode('@', $routeInfo->route->getAction('uses'))
        );

        $docText = Str::of($reflection->getDocComment())
            ->replace(['//', '/', ' * ', '*', '/*', '*/'], '')
            ->trim();
        $doc = new Doc("/** $docText */");

        $parsed = PhpDoc::parse($doc->getText());

        $operation->description(
            $parsed->getAttribute('description') != ''
                ? $parsed->getAttribute('description')
                : $parsed->getAttribute('summary')
        );
        $operation->summary($routeInfo->route->uri);
    }

    private function addResponse(Operation $operation, RouteInfo $routeInfo)
    {
        $returnType = $routeInfo->methodType->getAttribute(
            'inferredReturnType'
        );

        $returnTypes =
            $returnType instanceof Union ? $returnType->types : [$returnType];

        $responses = collect($returnTypes)
            ->merge($routeInfo->getMethodType()?->exceptions ?? [])
            ->map(function ($type) use ($routeInfo) {
                $docSource = $type
                    ->getAttribute('docNode')
                    ?->getAttribute('sourceClass');

                if ($docSource && $docSource !== $routeInfo->className()) {
                    $type->setAttribute('docNode', null);
                }

                return $type;
            })
            ->map($this->openApiTransformer->toResponse(...))
            ->filter()
            ->unique(
                fn($response) => ($response instanceof Response
                    ? $response->code
                    : 'ref') .
                    ':' .
                    json_encode($response->toArray())
            )
            ->values();

        [$responses, $references] = $responses->partition(
            fn($r) => $r instanceof Response
        );

        $responses = $responses
            ->groupBy('code')
            ->map(function (Collection $responses, $code) {
                if (count($responses) === 1) {
                    return $responses->first();
                }

                $responsesTypes = $responses
                    ->pluck('content.application/json.type')
                    ->map(fn($type) => $type ?: new OpenApiTypes\StringType())
                    ->unique(fn($type) => json_encode($type->toArray()))
                    ->values()
                    ->all();

                return Response::make((int) $code)
                    ->description($responses->first()->description)
                    ->setContent(
                        'application/json',
                        Schema::fromType(
                            count($responsesTypes) > 1
                                ? (new AnyOf())->setItems($responsesTypes)
                                : $responsesTypes[0]
                        )
                    );
            })
            ->values()
            ->merge($references)
            ->all();

        foreach ($responses as $response) {
            $operation->addResponse($response);
        }
    }
}

And added it to the scramble config

'extensions' => [
    LaravelActionsExtension::class
],