README

将OpenAPI规范转换为API，3，2，1... 完成！

Yii框架应用模板，用于快速构建API优先应用。

基于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和后端PHP web服务器。

您可以使用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宠物商店示例的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

您可以在https://npmjs.net.cn/package/@stoplight/spectral-cli#-documentation-and-community上找到有关Spectral的更多信息。

应用程序结构

此应用程序模板由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应用程序的公开Web目录
backend/ - 后端应用程序层
- config/ - 后端层的配置
  - components.php - 应用程序组件
  - app.php - Yii应用程序配置（+不同环境的覆盖配置app-*.php）
- controllers/ - 控制器类
- views/ - 视图文件
- web/ - 后端应用程序的公开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: "您的专业部署平台"赞助。

cebe / yii2-app-api

维护者

详细信息