repository·main·Indexed 24 days ago
https://github.com/dedoc/scrambleA Laravel package that automatically generates OpenAPI 3.1.0 documentation by analyzing code, eliminating the need for manual PHPDoc annotations. It provides an interactive UI viewer at `/docs/api` and a raw JSON specification at `/docs/api.json`. Includes CLI commands for analysis (`scramble:analyze`), caching (`scramble:cache`, `scramble:clear`), and exporting (`scramble:export`), as well as configuration options for parameter extractors and rule transformers.
Once installed, Scramble automatically provides two routes in your Laravel application:
/docs/api: The interactive UI viewer for browsing your API documentation./docs/api.json: The raw OpenAPI 3.1.0 specification in JSON format.Note: By default, these routes are only accessible in the local environment. To change this behavior or restrict access in other environments, you must define the viewApiDocs gate.
/docs/api
/docs/api.jsonTo add Scramble to your Laravel project, install the package using Composer:
composer require dedoc/scrambleThe Dedoc\Scramble\Infer\Scope\Index class acts as a central repository for type information discovered during analysis. It stores and provides access to ClassDefinition and FunctionLikeDefinition objects for classes, functions, and constants found in the analyzed codebase.
Key behaviors:
getClass() or getFunction() but hasn't been registered yet, the Index will attempt to reflect on it and build a definition on the fly.shouldAnalyzeAst is enabled for a specific class name, getClass() will use a ClassAnalyzer to perform a deep analysis. Otherwise, it falls back to a ShallowClassReflectionDefinitionBuilder.$classesDefinitions or $functionsDefinitions arrays for subsequent calls.The ExtensionsBroker acts as a central registry and dispatcher for inference extensions. When Scramble performs analysis, it uses the broker to query extensions for specific information.
Supported extension types managed by the broker include:
PropertyTypeExtension: Resolves property types.MethodReturnTypeExtension: Resolves return types for specific methods.AnyMethodReturnTypeExtension: Resolves return types for any method call (catch-all).MethodCallExceptionsExtension: Identifies exceptions thrown by method calls.StaticMethodReturnTypeExtension: Resolves return types for static methods.FunctionReturnTypeExtension: Resolves return types for global functions.AfterClassDefinitionCreatedExtension: Hooks into the process after a class definition is created.AfterSideEffectCallAnalyzed: Hooks into the process after a side-effect call is analyzed.TypeResolverExtension: Resolves complex or custom types via ReferenceResolutionEvent.You can control whether Scramble should throw exceptions when it encounters errors during the documentation generation process using Scramble::throwOnError(bool $throw = true).
true: An exception is thrown and documentation generation fails immediately.false: Documentation is still generated, but issues are added to the endpoint descriptions of the failed parts.Scramble::resolveTagsUsing(callable $tagResolver). The resolver callback receives a RouteInfo and an Operation object and should return an array of strings representing the tags.You can control which RuleTransformer or AllRulesSchemasTransformer classes are used to process validation rules in your OpenAPI documentation. The RuleTransformers class allows you to replace the default set of transformers, or add new ones to the beginning or end of the processing chain.
use(array $transformers): Replaces the entire set of transformers with the provided list of class strings.prepend(array|string $transformers): Adds one or more transformer class strings to the start of the transformer list.append(array|string $transformers): Adds one or more transformer class strings to the end of the transformer list.If no transformers are explicitly set using use(), Scramble uses the following default set:
AcceptedRuleEnumRuleInRuleFileRuleConfirmedRuleExistsRuleRegexRuleYou can enforce rules during documentation generation to ensure your API adheres to specific schema standards.
Scramble::enforceSchema(callable $cb, string|callable $errorMessageGetter, array $ignorePaths = [], bool $throw = true): Allows you to define a custom validation callback. If the callback returns false, the error is triggered.Scramble::preventSchema(string|array $schemaTypes, array $ignorePaths = [], bool $throw = true): A convenience method to forbid specific schema classes from appearing in your documentation.If $throw is set to true, generation will fail when a rule is violated. If false, errors will be collected and available via the scramble:analyze command.
If you need to access the actual instances of the configured transformers (rather than just their class names), use the instances method. This method resolves the classes from the container and injects any provided contextful bindings.
string $type: The class name or interface you want to filter by (e.g., RuleTransformer::class).array $contextfulBindings: An associative array of bindings to be injected into the transformer instances.Illuminate\Support\Collection containing the instantiated objects.You can extend Scramble's functionality by registering custom extension classes. Supported extension classes must implement one of the following interfaces: ExceptionToResponseExtension, OperationExtension, TypeToSchemaExtension, or InferExtension.
Use Scramble::registerExtension($className) for a single class or Scramble::registerExtensions($classNames) for an array of classes.
Scramble::configure() to access the GeneratorConfig for the default API. This allows you to customize how documentation is generated, including route resolution, server variables, and document transformers. To configure a specific named API instead of the default, use Scramble::registerApi($name, $config) or Scramble::getGeneratorConfig($name).