README

使用注解自动生成漂亮的Laravel API路由文档。

安装

需要PHP 7.4和Laravel 7或更高版本。

安装

您需要LaRecipe来提供自动生成的markdown文件。

运行 composer require --dev binarytorch/larecipe && composer require --dev icodestuff/ladocumenter 下载LaRecipe和LaDocumenter作为开发依赖

然后运行 php artisan larecipe:install 安装Larecipe

最后发布配置 php artisan vendor:publish --provider="Icodestuff\LaDocumenter\LaDocumenterServiceProvider"

演示视频

这是一个展示LaDocumenter包的YouTube视频

入门

只有api.php文件中的端点会被文档化。

生成文档

为了将注解编译为markdown，您需要运行

php artisan ladocumenter:generate

分组端点

所有端点都按组分组，便于组织。仅使用 @Group 在单个控制器类中分组端点，将其添加到控制器顶部，如下所示

示例

/**
 * @Group(name="Foo", description="This is an example group.")
 */
class FooController extends Controller
{

}

属性

• 名称（必需）
• 描述（可选）

记录端点

使用 @Endpoint 注解为一个控制器方法或端点。 注意，目前我们不支持闭包或资源 😕

示例

class FooController extends Controller
{
    /**
    * @Endpoint(name="Example", description="This is an example endpoint.")
     */
    public function bar()
    {
    
    }
}

属性

• 名称（必需）
• 描述（可选）

指定请求参数

要指定API路由接受的参数列表，请使用 @QueryParam 或 @BodyParam。

@BodyParam & @QueryParam 注解都接受名称、类型、必需、描述和示例。

@BodyParam 示例

class FooController extends Controller
{
    /**
    * @BodyParam(name="foo", type="string", status="required", description="An example body paramater", example="bar")
     */
    public function bar(FormRequest $request)
    {
    
    }
}

@QueryParam 示例

class FooController extends Controller
{
    /**
    * @QueryParam(name="foo", type="string", status="optional", description="An example query paramater", example="bar")
     */
    public function bar()
    {
    
    }
}

属性

• 名称（必需）
• 类型（必需）
• IsRequired（必需）
• 描述（可选）
• 示例（可选）

生成响应

要生成响应，您必须使用 @ResponseExample 注解。它包含响应的状态以及指向响应文件的链接，如下所示

class FooController extends Controller
{
    /**
    * @ResponseExample(status=200, file="responses/example.json")
     */
    public function bar()
    {
        return response()->json(['foo' => 'bar']);
    }
}

属性

• 状态（必需）
• 示例（必需）

请确保将您的响应添加到存储目录中，因为LaDocumenter会查找那里的响应。我们建议使用Laravel的测试套件自动生成响应。

指示身份验证状态

如果路由使用在 config/ladocumenter.php 文件中定义的中介，LaDocumenter会自动将端点标记为已认证。

'auth_middleware' => [
    'auth:sanctum',
    'auth'
],

如果您使用单独的认证中介，请确保在配置文件中定义它。