README

为您的 REST API 生成文档

此包允许您通过注解生成 REST API 的文档。然后由 LaRecipe 提供服务，生成美观的 API 文档。

注意，此包不稳定。我只在我的一个仓库中使用了它。

入门

安装 LaRecipe

您必须安装 LaRecipe 包，才能获得 API 文档生成器的优势。

通过 composer 安装 LaRecipe。

composer require binarytorch/larecipe

运行安装命令。

php artisan larecipe:install

安装 Documenter

通过 composer 安装 Documenter

composer require solomon04/documentation

发布提供者

php artisan vendor:publish --provider="Solomon04\Documentation\DocumentationServiceProvider"

步骤

1. 进入 API 控制器
2. 向文件中添加 可用的注解。
3. 运行 php artisan docs:generate

可用的注解

@Group

组注解用于在单个控制器类内分组端点。

属性

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

示例

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

}

@Meta

元注解用于记录单个端点。这将是控制器类中的函数。

属性

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

示例

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

@BodyParam

body param 注解用于记录单个端点请求中可用的请求体参数。

属性

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

示例

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()
    {
    
    }
}

@ResponseExample

响应示例注解用于为端点提供一个示例响应。

重要提示：响应示例文件必须存储在 storage/ 目录下。

属性

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

示例

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

示例 Laravel 应用程序

查看使用 Laravel REST API Documenter 生成的文档示例。

教程

在此处查看视频教程。