Scramble项目中如何隐藏文档UI中的Schemas部分

Scramble是一个用于生成API文档的工具，它能够自动从Laravel应用中生成OpenAPI规范的文档。在使用过程中，开发者可能会遇到需要隐藏文档UI中Schemas部分的需求，本文将详细介绍如何实现这一功能。

问题背景

在Scramble项目中，当开发者使用"Multiple API versions"功能管理多个API文档时，可能会发现某些资源类（Resource Classes）会出现在文档UI的Schemas部分，即使这些资源类并没有被当前API的控制器或资源类引用。这可能会造成文档界面的混乱，影响开发者对核心API的理解和使用。

解决方案

经过社区讨论和技术验证，发现可以通过配置elements-api标签的hideSchemas属性来隐藏Schemas部分。具体实现步骤如下：

1. 首先需要发布Scramble的配置文件，通过运行以下Artisan命令：

php artisan vendor:publish

在提示中选择Dedoc\Scramble\ScrambleServiceProvider以发布配置文件。

2. 在生成的docs.blade.php文件中，找到elements-api标签，添加hideSchemas属性：

<elements-api
    id="docs"
    tryItCredentialsPolicy="{{ $config->get('ui.try_it_credentials_policy', 'include') }}"
    router="hash"
    @if($config->get('ui.hide_try_it')) hideTryIt="true" @endif
    logo="{{ $config->get('ui.logo') }}"
    hideSchemas="true"
/>

技术原理

这个解决方案利用了Stoplight Elements的配置选项。Stoplight Elements是Scramble底层使用的文档渲染引擎，它提供了丰富的配置选项来自定义文档UI的显示方式。hideSchemas属性就是其中之一，当设置为true时，会完全隐藏文档中的Schemas部分。

注意事项

1. 在隐藏Schemas部分前，建议确认这些Schema确实不需要展示。有时Schema被显示可能是因为存在深层引用关系，而不是配置错误。

2. 隐藏Schemas部分后，相关的模型定义仍然会出现在各个端点的描述中，不会影响文档的完整性。

3. 这一配置适用于Scramble 0.12.9及以上版本。

总结

通过简单的配置调整，开发者可以灵活控制Scramble生成的API文档界面，隐藏不需要显示的Schemas部分，使文档更加简洁清晰。这一功能特别适合那些希望专注于端点描述而不是底层数据结构的API文档场景。