README

实时预览

点击此处查看输出结果。

安装

需要PHP 7.2和Laravel 6.x或更高版本。

composer require --dev ronanflavio/laradocs-generate

更新composer后，将服务提供者添加到config/app.php中的providers数组中

Ronanflavio\LaradocsGenerate\LaradocsGenerateServiceProvider::class,

生成文档

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

php artisan docs:generate

此命令将在您的resource文件夹中创建routes.json文件。该文件将用于向视图提供数据。您可能希望将routes.json文件添加到您的.gitignore中。

通过/docs URI访问您的应用程序主机以查看文档页面

例如：http://127.0.0.1:8000/docs

编写文档

此包的主要目标是指示URI参数、请求体参数以及响应中包含的内容。

为了实现这一点，您可能需要在控制器类、操作和DTO属性上编写一些自定义PHPDocs。让我们看看一些实际示例

输入请求和响应对象

要指示URI参数类型，请使用默认的@param注解。

要指示请求中必须提供的类对象，必须在@request注解中编写该类对象的完全限定名称。

要指示将返回的类对象，必须在@response注解中编写该类对象的完全限定名称。如果没有要返回的类对象，只需输入变量类型（例如：boolean，int等...）。如果没有@response，则提供void。

<?php

// namespace and uses here...

/**
 * Users management
 * 
 * Here will be shown the description of
 * your UsersController group. If there is
 * no description, the class name will be
 * shown instead.
 */
class UsersController extends Controller
{
    /**
     * Lists all users
     * @response \App\DataTransferObjects\User\ListUsersDto
     */
    public function index()
    {
        // your code here...
    }

    /**
     * Returns the details about the given user
     * @param string $id
     * @response \App\DataTransferObjects\User\UserDetailsDto
     */
    public function details(string $id)
    {
        // your code here...
    }
    
    /**
     * Creates a new user
     * @request \App\DataTransferObjects\User\CreateUserDto
     * @response \App\DataTransferObjects\User\UserDetailsDto
     */
    public function create(CreateUserRequest $request)
    {
        // your code here...
    }

输入DTOs的属性规范

要指示属性变量的类型，可以使用标准的@var注解。如果您想更具体地说明该属性，也可以使用@example注解来指示该属性的实用示例。以下是一些代码示例

<?php

namespace App\DataTransferObjects\User;

use App\DataTransferObjects\DataTransferObject;

class CreateUserDto extends DataTransferObject
{
    /**
     * @var string
     * @example email@example.local
     */
    public $email;

    /**
     * @var string
     * @example John Doe
     */
    public $name;

    /**
     * @var string
     * @example 123456
     */
    public $password;

    /**
     * @var string
     * @example 4c0c9e5d-f18f-4197-8531-02c90f9a81e0
     */
    public $role_id;
}

发布

通过以下命令发布配置文件

php artisan vendor:publish --provider="Ronanflavio\LaradocsGenerate\LaradocsGenerateServiceProvider" --tag=laradocs-config

这将在您的config目录中创建docs.php文件。

您还可以通过以下命令发布视图blade文件

php artisan vendor:publish --provider="Ronanflavio\LaradocsGenerate\LaradocsGenerateServiceProvider" --tag=laradocs-views

这将在您的resource/views目录中创建docs.blade.php文件。

许可证

Laradocs Generate是免费软件，许可协议为MIT。

ronanflavio / laradocs-generate

维护者

详细信息