Scramble 项目常见问题解决方案

Scramble 项目常见问题解决方案

scramble Modern Laravel OpenAPI (Swagger) documentation generator. No PHPDoc annotations required. 项目地址: https://gitcode.com/gh_mirrors/sc/scramble

1. 项目基础介绍和主要编程语言

Scramble 是一个现代化的 Laravel 开源项目，用于生成 OpenAPI（Swagger）文档。该项目无需手动编写 PHPDoc 注解，即可自动为 Laravel 项目生成 API 文档。生成的文档遵循 OpenAPI 3.0.1 格式。Scramble 项目的主要编程语言是 PHP，同时也使用了 Laravel 的 Blade 模板语言。

2. 新手常见问题及解决步骤

问题一：如何安装 Scramble？

问题描述： 新手在使用 Scramble 之前，需要知道如何正确安装该包。

解决步骤：

1. 打开终端，切换到你的 Laravel 项目根目录。
2. 运行以下命令安装 Scramble：

   composer require dedoc/scramble
   

3. 安装完成后，使用 php artisan migrate 命令来迁移数据库。

问题二：如何查看生成的 API 文档？

问题描述： 安装 Scramble 后，新手可能不知道如何查看生成的 API 文档。

解决步骤：

1. 在 Laravel 的 config/app.php 文件中，确保已经注册了 dedoc\Scramble\ScrambleServiceProvider 服务提供者。
2. 在 Laravel 的 routes/web.php 或 routes/api.php 文件中，添加以下路由：

   Route::get('/docs/api', 'dedoc\Scramble\Http\Controllers\DocumentationController@api');
   Route::get('/docs/api/json', 'dedoc\Scramble\Http\Controllers\DocumentationController@apiJson');
   

3. 访问 /docs/api 将会看到 API 文档的 UI 视图，访问 /docs/api/json 将会得到 JSON 格式的 OpenAPI 文档。

问题三：如何在不同环境下配置文档的访问权限？

问题描述： 默认情况下，文档路由只对本地环境可用，新手可能需要知道如何在不同环境下配置访问权限。

解决步骤：

1. 在 config/scramble.php 配置文件中，可以设置 enabled 选项来控制文档的访问权限。
2. 如果需要在不同环境中设置不同的访问权限，可以通过 Laravel 的环境配置文件（如 .env）来设置环境变量，并在 config/scramble.php 中引用这些变量。
3. 例如，可以在 .env 文件中添加以下内容：

   SCRAMBLE_ENABLED=true
   

   然后在 config/scramble.php 中引用：

   'enabled' => env('SCRAMBLE_ENABLED', true),
   

4. 重新启动应用以使配置生效。

scramble Modern Laravel OpenAPI (Swagger) documentation generator. No PHPDoc annotations required. 项目地址: https://gitcode.com/gh_mirrors/sc/scramble