README

设计用于与 Laravel JSON:API 一起使用

!!! 免责声明：此项目仍在开发中，可能包含许多错误等 !!!

它能够做什么和不能做什么

能够

为所有默认 Laravel JSON:API 路由生成模式/响应/请求/错误
使用已播种的数据库生成示例

还不能

生成自定义
为自定义操作生成
为自定义过滤器生成
为任何自定义内容生成
为MorphTo关系生成
生成分页元数据
生成包含项
生成身份验证/授权

待办事项

命令用于生成到存储文件夹
通过GitHub Actions运行基本测试套件
通过配置添加额外的操作描述
添加标签 & x-tagGroups（通过配置）
添加测试（使用laraveljsonapi的占位符来集成所有功能）
添加自定义操作
按操作拆分模式/请求/响应
考虑字段属性
- bool只读
- bool隐藏
- 基于闭包的只读（创建/更新）
- 基于闭包的隐藏
列表可排序字段
修复包含和关系
- 添加关系路由
- 添加包含项
添加身份验证
添加自定义查询/过滤器
添加一种记录自定义操作的方法
整理代码!!
将 cebe/php-openapi 替换为 goldspecdigital/oooas
迁移到一个受 vyuldashev/laravel-openapi 启发的架构
在操作/类上使用php8属性来生成自定义文档

🙏 基于 martianatwork，glennjacobs 和 byte-it 的初始原型。

安装

通过Composer

composer require swisnl/openapi-spec-generator

发布配置文件

php artisan vendor:publish --provider="LaravelJsonApi\OpenApiSpec\OpenApiServiceProvider"

用法

生成Open API规范

php artisan jsonapi:openapi:generate v1

请注意，需要已播种的数据库！已播种的数据将用于生成样本。

描述

可以通过实现 DescribesEndpoints 接口添加对端点的描述。添加的方法接收生成的路由名称作为参数。这可以用来生成所有模式端点的描述。

class Post extends Schema implements DescribesEndpoints
{
    public function describeEndpoint(string $endpoint) {
        if ($endpoint === 'v1.posts.index') {
            return 'Description for index method';
        }

        return 'Default description';
    }
}

生成文档

Speccy

预览文档的一种快速方法是使用 speccy serve 命令。

确保您已全局安装Speccy，然后可以使用以下命令

speccy serve storage/app/v1_openapi.yaml

警告：看起来 Speccy 已被废弃 (wework/speccy#485)。

Laravel Stoplight Elements

通过在Laravel应用程序中直接使用OpenAPI文档，轻松地将API文档发布到本地路由。

为此，您必须在公共位置生成规范，例如Laravel应用程序中可用的本地'public'磁盘。
OPEN_API_SPEC_GENERATOR_FILESYSTEM_DISK='public'

安装它后，您应该设置其URL配置：STOPLIGHT_OPENAPI_PATH。例如，如果您使用的是'public'磁盘

OPEN_API_SPEC_GENERATOR_FILESYSTEM_DISK='public'

# '/storage' is the default 'public' URL.
STOPLIGHT_OPENAPI_PATH='/storage/v1_openapi.json'

注意：如果您需要更动态地获取规范URL的访问权限（例如，在S3中，您可能需要使用临时URL），您可以发布其Blade模板并替换一些行来生成您自己的URI。此外，您可能需要添加一个Fetch拦截器来将其与您的认证方法集成。

使用其默认路由，您只需访问到您的/api/docs路由即可预览您的规范！

有关其他选项，请参阅其配置文档。

独立的Stoplight Elements Web组件

除了之前的Laravel包之外，您还可以单独使用Stoplight Elements。它可作为React组件或Web组件提供，使其更容易集成到具有自身导航的现有内容管理系统。

当您需要在路由系统中进行更多高级定制、将其集成到现有的Vue|React|Vanilla应用程序中或将它发布为非Laravel静态HTML站点时，这很有用。但...您必须手动设置它。😅

集成到Vue应用程序中的Web组件

您可以通过以下说明使用独立的Web组件，将其抓入Blade模板并装饰您的视图。

它具有高级选项，如tryItCredentialPolicy="same-origin"，以便使用基于cookie的认证（如Sanctum）。

此外，在您的Blade视图或Vue的应用程序初始化器中，由于该包使用Fetch API，您可以为自定义“尝试一下”功能添加拦截器，例如为请求添加默认的Content-Type和/或Accept头，使其为'application/vnd.api+json'。

其他选项

您可以在https://openapi.tools/#documentation查看更详尽的选项列表。

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

测试

$ composer test

贡献

有关详细信息，请参阅CONTRIBUTING和CODE_OF_CONDUCT。

安全

如果您发现任何安全问题，请通过电子邮件security@swis.nl而不是使用问题跟踪器。

鸣谢

许可证

Apache License 2.0。所有对原始作品的显著更改都可以在CHANGELOG中找到。有关更多信息，请参阅许可证文件。

本软件包为Treeware。如果您在生产环境中使用它，我们请求您为世界买一棵树以感谢我们的工作。通过为Treeware森林做出贡献，您将创造就业机会，并为当地家庭恢复野生动物栖息地。

SWIS ❤️ 开源

SWIS 是一家来自荷兰莱顿的网页代理机构。我们热爱与开源软件合作。

社区/sly-soft-community / jsonapi-spec-generator

维护者

详细信息