README

此软件包使用 oas-tools 进行模式解析和实用函数。如果您想使用 OAS2 和 OAS3 模式，那么请自由地检查它！

简介

API 模式，尤其是 OpenAPI 规范模式，正在帮助我们创建一个有序和井井有条的互联网，其中 RESTful API 可以轻松互操作并相互协作。然而，我看到的大多数项目都是关于从服务器端代码自动生成文档——也许还从这些模式中生成客户端或 SDK 代码。关于“先从模式开始”的方法的项目似乎很少，其目标是编写我们的模式并从这些模式本身自动生成服务器代码。

这种“先从模式开始”的哲学是我组合这个项目的灵感。如果我们能花更少的时间编写重复的模板代码来完成常见功能，而只是用 JSON 或 YAML 编写规范，然后在几分钟内运行一个 API 原型，那岂不是很好？这就是 oas-lumen 项目的最终目标。

在此，我应该声明一个来自 Python 社区的灵感来源： Connexion。Zalando 的 Connexion 是一个真正伟大的项目，我与它一起工作了几年，从中学到了很多。然而，在这段时间里，我开始遇到我在工作的 API 中遇到的一些问题。

首先，我发现从规范自动生成的代码和功能与我不可避免地要添加的定制代码之间存在紧张关系。我需要一种方法，可以从我的初始规范中尽可能自动生成，添加我自己的定制代码，然后更改我的规范并重新生成代码，而不破坏我的定制工作。以干净的方式解决这个工作流程问题是这个项目的目标之一。

其次，为每个网络请求动态生成大量路由、内容协商和验证规则显然在性能方面很慢。因此，这是我想要解决的第二个问题。这个项目的第二个最终目标是提供从快速原型工具到生产代码的平滑过渡。需要有一个明确的过程，通过这个过程，你可以将你的按需原型迁移到性能代码，为生产做准备，一旦探索性开发阶段完成。

安装

有一个配套的存储库，oas-lumen-example，演示了如何使用 OAS3 模式引导 Lumen REST API 而不编写任何代码。前往示例项目，并在那里的说明书中完成教程，可能是了解这个项目希望实现什么的最有效方式。

警告：Alpha / 概念验证项目。尚未准备好用于生产！ :)

但是，如果您想直接安装软件包，可以使用软件包管理器 composer 来安装 oas-lumen。

composer require danballance/oas-lumen

功能

为了实现以下功能，需要在规范中添加一系列OAS扩展参数。这些参数在下一节中详细说明。

• 路由从模式中动态读取并分配给控制器/操作
• 默认的CRUDL控制器实现为大多数标准用例提供了创建、读取、更新、删除和列表操作。
• 提供了一组“内置电池”，合理的默认值，但一切都可以根据需要扩展和定制。
• API规范中定义的任何请求体都可以在请求到来时自动验证，如果发现问题，则返回HTTP 400状态码和验证错误说明。
• 提供了内容协商的中间件，直接处理406和415错误。
• 基于Accept头部的可插拔序列化。最初仅支持application/json和application/hal+json，但可以添加更多媒体类型（有关计划，请参阅路线图）。
• 通用的存储接口，将OAS模式请求映射到存储实现。如果你真的需要，可以编写自己的存储实现！
• 初始的默认存储实现使用Doctrine，并且最终可以处理关系型ORM和基于文档的ODM，多亏了Doctrine通用项目 - 当前实现可以在这里找到。
• 路线图中有很多更多功能计划的计划和想法！ :)

规范扩展

操作对象扩展

• 'x-action' - 指定用于处理此操作的控制器动作
• 'x-controller' - 指定用于处理此操作的控制器
• 'x-resource' - 指定此操作所属的资源（或实体）

操作.parameter对象扩展

• 'x-filter: attribute' - 指示此参数是用于在列表操作中查询资源集合的属性
• 'x-filter: limit' - 指示此参数在列表操作返回的资源集合分页时扮演限制的角色

模式对象扩展

• 'x-storage-engine: mysql'（示例）- 此参数的值应由使用的存储实现定义。例如，当使用Doctrine存储实现时，最终可以在一个API中混合MySQL、PostgreSQL和MongoDB资源。
• 'x-storage-name: pet'（示例）- 允许指定底层数据库模式的名字，在可能不同的情况下。例如，数据库表名。
• 'x-primary-key: true' - 指示此模式字段是底层数据库实现的主键。

路线图

@TODO 即将推出！

贡献

欢迎提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

请确保根据需要更新测试。

许可证

MIT