README

从OpenAPI规范到API，3，2，1... 完成！

为快速构建API优先应用程序的Yii框架应用程序模板。

基于yii2-openapi（代码生成器）和php-openapi（规范读取器和验证器）。

演示

概述

此应用程序模板不包含任何有用的代码，它只为您的API项目提供了目录结构。所有代码都是从OpenAPI API描述文件生成的。

当使用此模板工作时，您遵循API设计优先方法。因此，要使用此应用程序模板开始构建API，您需要首先有一个API描述。如果您还没有，您可能首先想要查看以下资源

如果您有OpenAPI描述，您可以继续进行以下步骤

设置
生成代码

更多文档和指南可以在/docs中找到。

设置

有两种不同的方法

直接在您的机器上运行PHP
使用Docker

直接PHP

在您的机器上安装PHP和数据库服务器，您可以运行以下命令

composer create-project php-openapi/yii2-app-api my-api
cd my-api
cp env.php.dist env.php
cp config/components-ENV.local.php config/components-dev.local.php

您需要调整config/components-dev.local.php以配置您的数据库连接。

之后，运行make start和make stop以控制API和后端的服务器。

您可以使用XDEBUGW=1为Web服务器启用xdebug，例如make XDEBUGW=1 start。

您现在可以继续生成代码。

使用Docker

您需要Docker和Docker Compose安装。

创建仓库

composer create-project php-openapi/yii2-app-api my-api

对于最简单的方法，您需要GNU make，然后运行

make start-docker

这使用docker-compose启动API和后端包括数据库的docker容器。

您现在可以继续生成代码。

注意：如果您没有GNU make，您需要复制如PHP直接部分中的配置文件，然后运行
cp docker-compose.override.dist.yml docker-compose.override.yml
docker-compose up -d
docker-compose exec backend-php sh -c 'cd /app && composer install'

生成代码

在此阶段，您可以按照以下说明开始生成您的API代码以进行试验。如果您想开始一个真正的项目而不是仅仅玩耍，您可以在docs/README.md中找到更多详细的文档，特别是“入门”部分。

控制台

提示：如果您使用Docker，请在运行以下任何命令之前运行make cli。

运行./yii gii/api以生成您的API代码。--openApiPath参数指定OpenAPI规范文件的路径。以下示例将生成OpenAPI petstore示例的API代码。

./yii gii/api --openApiPath=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml

注意：如果OpenAPI规范文件在文件系统中本地存在，则openApiPath必须指定为绝对路径，相对路径将无法正确工作。在基于UNIX的操作系统上，它必须以/开头。例如：/home/user/documents/MyProjectOpenAPISpec.yml

运行 ./yii gii/api --help 查看配置选项列表。您还可以在 config/gii-generators.php 中调整配置。

然后设置数据库

./yii migrate/up
./yii faker

Web

要使用 Web 生成器，请打开 http://localhost:8338/gii 并选择 REST API Generator。

输入 "OpenAPI 3 规范文件" 的路径或 URL，例如 https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml。

点击 "预览"。

点击 "生成" 以生成 API 文件。

然后在命令行中运行以下命令来设置数据库

./yii migrate/up
./yii faker

试试看

cd api
make start

您的 API 现在可在 http://localhost:8337/ 上使用。尝试通过 curl 访问您的规范端点。

$ curl http://localhost:8337/pets
[
    {
        "name": "Eos rerum modi et quaerat voluptatibus.",
        "tag": "Totam in commodi in est nisi nihil aut et."
    },
    {
        "name": "Voluptas quia eos nisi deleniti itaque aspernatur aspernatur.",
        "tag": "Temporibus id culpa dolorem sequi aut."
    },
    {
        "name": "Facere aut similique laboriosam omnis perferendis et.",
        "tag": "Quo harum quo et ea distinctio non quam."
    },
    ...
]

检查 OpenAPI 规范

您可以使用检查器来检查您的 OpenAPI 规范文件的正确性

make lint-js  # run spectral lint
make lint-php # run php-openapi validate
make lint     # run both of the above commands

有关 spectral 的更多信息，请访问 https://npmjs.net.cn/package/@stoplight/spectral-cli#-documentation-and-community。

应用程序结构

此应用程序模板由 3 个应用程序层组成

api，包含用于 REST API 的 Yii 应用程序。
console，包含用于控制台命令、cron作业或队列的 Yii 应用程序（yii 命令）。
backend，包含用于 API 数据的 CRUD 后端应用的 Yii 应用程序。

以下列表更详细地解释了目录结构

api/ - API 应用程序层
- config/ - API 层的配置
  - url-rules.php - 自定义 URL 规则
  - url-rules.rest.php - 由 OpenAPI 描述生成的 URL 规则
  - components.php - 应用程序组件
  - app.php - Yii 应用程序配置（+不同环境的覆盖 app-*.php）
- controllers/ - 由 OpenAPI 描述生成的控制器类
- web/ - API 应用程序的公开网页目录
backend/ - 后端应用程序层
- config/ - 后端层的配置
  - components.php - 应用程序组件
  - app.php - Yii 应用程序配置（+不同环境的覆盖 app-*.php）
- controllers/ - 控制器类
- views/ - 视图文件
- web/ - 后端应用的公开网页目录
common/ - 公共代码文件
- models/ - 由 OpenAPI 描述生成的模型类
- migrations/ - 由 OpenAPI 描述生成的数据库迁移
config/ - 所有应用程序层的通用配置
- components.php - Yii 应用程序组件（+不同环境的覆盖 components-*.php）
- env.php - 环境设置（YII_DEBUG，YII_ENV，路径别名，composer 自动加载器）
- events.php - 类级事件监听器
- gii-generators.php - Gii 代码生成器的配置（允许为 ApiGenerator 设置默认值）
- params.php - Yii::$app->params 的配置
console/ - 控制台应用程序层
- config/ - 控制台层的配置
  - components.php - 应用程序组件
  - app.php - Yii 应用程序配置（+不同环境的覆盖 app-*.php）
logs/ - 日志文件
runtime/ - 临时运行时文件

开发

以下命令在开发此项目时非常有用

./yii gii/api --openApiPath=/app/openapi/schema.yaml --generateMigrations=0  --generateControllers=0 --generateUrls=0

./yii gii/api --openApiPath=/app/openapi/schema.yaml --generateMigrations=1  --generateControllers=0 --generateUrls=0 --generateModels=0 --generateModelFaker=0

支持

需要帮助您的 API 项目吗？

提供专业支持、咨询以及软件开发服务

https://www.cebe.cc/en/contact

此库的开发由 cebe.:cloud: "您的专业部署平台" 赞助。

php-openapi / yii2-app-api

维护者

详细信息