在Scribe项目中通过自定义策略实现端点描述文件化

在实际API开发过程中，我们经常需要为多个端点(Endpoint)编写相同或相似的描述文档。传统做法是在每个端点的Docblock中重复编写HTML内容，这不仅违反了DRY(Don't Repeat Yourself)原则，也不利于文档的维护和格式检查。本文将介绍如何在Scribe项目中通过自定义策略实现端点描述的文件化管理。

问题背景

Scribe是一个优秀的API文档生成工具，默认支持通过Docblock注释或Endpoint属性来定义端点描述。但在实际应用中，开发者可能会遇到以下痛点：

1. 相同描述内容需要在多个端点间重复编写
2. 无法对文档内容进行格式校验和规范化处理
3. HTML内容直接嵌入代码中影响可读性

解决方案

Scribe提供了灵活的扩展机制，允许开发者通过自定义属性和策略来实现更高级的文档管理方式。我们可以创建一个自定义属性EndpointFromFile，将端点描述内容提取到外部文件中。

实现步骤

1. 创建自定义属性类： 类似于Scribe内置的ResponseFromFile属性，我们可以定义一个EndpointFromFile属性，用于指定描述文件的路径。

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class EndpointFromFile
{
    public function __construct(public string $path)
    {
    }
}

2. 实现自定义策略： 继承PhpAttributeStrategy基类，实现从文件中读取描述内容的逻辑。

use Knuckles\Scribe\Extracting\Strategies\PhpAttributeStrategy;

class EndpointDescriptionFromFile extends PhpAttributeStrategy
{
    protected string $attributeName = EndpointFromFile::class;
    
    protected function extractFromAttributes(
        array $attributesOnMethod,
        array $attributesOnFormRequest = [],
        array $attributesOnController = []
    ): ?array {
        // 实现从文件读取描述内容的逻辑
    }
}

3. 注册策略： 在Scribe配置文件中注册新创建的策略，使其生效。

'strategies' => [
    'metadata' => [
        \Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
        \App\Strategies\EndpointDescriptionFromFile::class,
        // 其他策略...
    ],
    // 其他策略组...
],

优势与最佳实践

这种文件化管理端点描述的方式带来了以下优势：

1. 内容复用：多个端点可以引用同一个描述文件，避免重复编写
2. 格式控制：可以对描述文件进行专门的格式校验和规范化处理
3. 维护便利：HTML内容与代码分离，提高可读性和可维护性
4. 版本控制：描述文件可以单独进行版本管理

在实际应用中，建议：

1. 为描述文件建立统一的目录结构
2. 对描述文件进行命名规范化
3. 为描述文件添加Markdown或HTML格式校验
4. 考虑实现描述文件的自动生成和更新机制

总结

通过Scribe的扩展机制，我们可以灵活地定制API文档生成流程，满足各种复杂场景的需求。将端点描述提取到外部文件不仅解决了重复编写的问题，还为文档管理提供了更多可能性。这种模式也可以扩展到其他类型的文档内容管理上，如响应示例、参数说明等，实现API文档的全面文件化管理。