README

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

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

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

能够

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

目前还不能

生成过程的定制
为自定义动作生成
为自定义过滤器生成
为任何自定义内容生成
为 MorphTo 关系生成（MorphToMany 可用）
生成分页元数据
生成包含
生成身份验证/授权

TODO

命令生成到存储文件夹
使用 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 是一家来自荷兰莱顿的网站代理机构。我们热爱与开源软件合作。

swisnl / openapi-spec-generator

维护者

详细信息