README

Auto Documentation 是一个用于为 Laravel 生成 API 文档的库。

功能

此包允许您生成 API 文档。基于 OpenAPI 3 和 Redoc

安装后，您可以执行以下操作

// Create documentation for path
Path::get('/your/api/{endpoint}', 'Your endpoint name')
    ->group('Some group')
    ->tag('Some tag') // or ->tags(['First tag', 'Second tag'])
    ->parameters([
        PathParameter::make('endpoint')
            ->required()
            ->type(Type::string)
            ->example('myGoodEndpoint'),
    ])
    ->jsonRequest([
        StringProperty::make('some_property_name')->required()
            ->description('You can add description for each property'),
        BooleanProperty::make('one_more_property'),
    ])
    ->successfulResponse([
        StringProperty::make('message')->example('Success response'),
    ])
    ->secure();

// Or you can use existing schemas
Path::get('/your/api/endpoint', 'Your endpoint name')
    ->group('Some group')
    ->tag('Some tag') // or ->tags(['First tag', 'Second tag'])
    ->parameters([ExampleParameter::make()])
    ->jsonRequest(ExampleSchema::make())
    ->successfulResponse(ExampleSchema::make())
    ->secure();

//Also you can do that for routes
Route::make('name.of.your.route', 'Example route')
    ->group('Some other group')
    ->tag('Other tag')
    ->requestBodyFromRequestClass() // Get request body from validation rules in request class
    ->successfulResponse(ExampleSchema::make())
    ->secure();

安装

您可以通过 Composer 安装此包

composer require andrii-hrechyn/auto-documentation

然后您可以运行以下命令

php artisan auto-doc:install

此命令在您的根目录中创建 docs 文件夹，并包含一些文档示例。此外，此命令还将自动加载添加到您的 composer.json 文件中

    ...
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            ...
            "Docs\\": "docs"
        }
    },
    ...

docs 文件夹包含与文档相关的所有文件。文件夹结构

├── Components
│   ├── Parameters
│   │   └── ExampleParameter.php
│   └── Schemas
│       ├── ExampleSchema.php
│       └── ExampleSubSchema.php
├── Paths
│   ├── testPaths.php
│   └── testRoute.php
└── info.php

info.php 包含有关 API 的通用信息（信息、服务器、安全、默认安全和外部文档链接）

用法

要生成文档，请运行以下命令

php artisan auto-doc:generate

此命令将 info.php 文件和 docs 文件夹中的所有路径作为输入，并在 storage/app/auto-docs 中生成 documentation.yaml

配置

...

测试

...

许可证

此库根据 MIT 许可证授权。有关详细信息，请参阅 LICENSE 文件。

鸣谢

• 开发者：Andriy Hrechyn
• 电子邮件： andriy.hrechyn@gmail.com