README

• 描述;
• 安装;
• 主要命令;
• 用于生成单个组件的命令;
• 使用;

描述

此包添加了用于生成yaml格式的OpenApi文档的命令行工具

* 此包仅与Laravel框架兼容

安装

1. 使用composer依赖管理器安装包

   composer require synergyhub/docs-generator:dev-master --dev
   

2. 如果未使用自动发现，则需要在config/app.php中注册服务提供者 'Synergyhub\DocsGenerator\Providers\DocsServiceProvider'

   return [
   //  other configs
    'providers' => [
   //      other providers
        \Synergyhub\DocsGenerator\Providers\DocsServiceProvider::class
    ],
   ];
   

3. 运行命令以创建配置文件（configs/docs-generator/...）

   $ php artisan vendor:publish --tag=docs-generator:configs
   

4. 填写配置
5. 运行命令以创建将包含文档的目录

   $ php artisan vendor:publish --tag=docs-generator:docs
   

   完成这些步骤后，将提供用于生成文档的命令行工具

主要命令

根据jsonapi规范生成文档组件

$ php artisan docs-generate:components

• 运行命令时，将提示选择要为其生成文档的模型
• 为了正常工作，必须在config/docs-generator/entity-settings.php文件中填写模型的设置

为在config/docs-generator/entity-settings.php文件中有配置的实体生成文档组件

$ php artisan docs-generate:components --all

为在config/docs-generator/entity-settings.php文件中有配置的实体生成路由

$ php artisan docs-generate:path --all

将文档编译到文件 .../src/openapi.yaml

$ php artisan docs-generate:build

用于生成单个组件的命令

为OpenApi文档生成parameters组件

$ php artisan docs-generate:params

为OpenApi文档生成request-body组件

$ php artisan docs-generate:request

为OpenApi文档生成request组件

$ php artisan docs-generate:response

为OpenApi文档生成schema组件

$ php artisan docs-generate:schema

使用

1. 需要在项目中安装此包
2. 填写配置文件（entity-settings.php）
3. 执行命令

   $ php artisan docs-generate:components --all
   

   $ php artisan docs-generate:path --all
   

   $ php artisan docs-generate:build
   

4. 之后，需要创建两个路由
   1. 用于文档文件
   2. 用于显示文档的图形界面

示例

$configs = config('docs-generator.settings');

Route::get($configs['docs_url'], function () use ($configs) {
    return view('redoc.spec');
})->name('docs-generator.spec');

Route::get($configs['document_url'], function () use ($configs) {
    return File::get(sprintf('%s/openapi.yaml', $configs['docs_path']));
})->name('docs-generator.spec.document');```

之后，可以在浏览器中打开文档
路径： https://{你的域名}/{在settings.php中指定的路径}

示例： https://example.ru/api/v1/docs/spec