yii2-app-api
OpenAPI Spec to API in 3, 2, 1... done!
Yii Framework Application Template for quickly building API-first applications.
Based on yii2-openapi (code generator) and php-openapi (specification reader and validator).
Demo
Overview
This application template does not contain any useful code, it only provides the directory structure for your API project. All the code is generated from an OpenAPI API description file.
When working with this template you follow the API Design-First Approach. So to get started building an API with this application template you need an API description first. If you don't have one yet, you might want to check the following resources first:
If you have an OpenAPI description, you can continue with the next steps:
More Docs and Guides can be found in /docs.
Setup
There are two different ways:
- PHP directly on your machine
- Using Docker
PHP directly
Having PHP and a database server installed on your machine, you can run the following commands:
composer create-project cebe/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
You need to adjust config/components-dev.local.php to configure your database connection.
After that, run make start and make stop to control the PHP webservers for API and backend.
You can now continue with generating code.
Using Docker
You need Docker and Docker Compose installed. For the easiest way you need GNU make, then run:
make docker-up
This uses docker-compose to start docker containers for the API and the backend including a database.
You can now continue with generating code.
Note: If you don't have GNU make, you need to copy the configuration files as in the PHP directly section, then run:
docker-compose up -d docker-compose exec backend-php sh -c 'cd /app && composer install'
Generate Code
Console
Tip: If you use Docker, run
make clibefore running any of these commands.
Run ./yii gii/api to generate your API code. The --openApiPath parameter specifies the path to your OpenAPI spec file. The following example will generate API code for the OpenAPI petstore example.
./yii gii/api --openApiPath=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml
Run ./yii gii/api --help for a list of configuration options. You may also adjust the configuration in config/gii-generators.php.
Then set up the database:
./yii migrate/up
./yii faker
Web
To use the web generator, open http://localhost:8338/gii and select the REST API Generator.
Enter the path or URL to the "OpenAPI 3 Spec file", e.g. https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml.
Click "Preview":
Click "Generate" to generate API files.
Then set up the database by running the following commands on the command line:
./yii migrate/up
./yii faker
Try it
cd api
make start
Your API is now available at http://localhost:8337/. Try to access an endpoint of your spec via 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."
},
...
]
Application structure
This application template consists of 3 application tiers:
api, contains the Yii application for the REST API.console, contains the Yii application for console commands, cronjobs or queues (yiicommand).backend, contains the Yii application for a CRUD backend on the API data.
The following list explains the directory structure in more detail:
-
api/- API application tierconfig/- configuration for API tierurl-rules.php- custom URL rulesurl-rules.rest.php- URL rules generated from OpenAPI Descriptioncomponents.php- application componentsapp.php- Yii application config (+ overrides for different environmentsapp-*.php)
controllers/- Controller classes generated from OpenAPI Descriptionweb/- public web directory for API application
-
backend/- Backend application tierconfig/- configuration for Backend tiercomponents.php- application componentsapp.php- Yii application config (+ overrides for different environmentsapp-*.php)
controllers/- Controller classesviews/- View filesweb/- public web directory for Backend application
-
common/- common code filesmodels/- model classes generated from OpenAPI Descriptionmigrations/- database migrations generated from OpenAPI Description
-
config/- Common configuration for all application tierscomponents.php- Yii application components (+ overrides for different environmentscomponents-*.php)env.php- Environment setup (YII_DEBUG, YII_ENV, path aliases, composer autoloader)events.php- Class wide event listenersgii-generators.php- configuration for the Gii code generator (allows to set default values for the ApiGenerator)params.php- Configuration forYii::$app->params
-
console/- Console application tierconfig/- configuration for Console tiercomponents.php- application componentsapp.php- Yii application config (+ overrides for different environmentsapp-*.php)
-
logs/- log files -
runtime/- temporary runtime files
Support
Need help with your API project?
Professional support, consulting as well as software development services are available:
https://www.cebe.cc/en/contact
Development of this library is sponsored by cebe.
65 Oct 31, 2022
3 Jul 28, 2022
6 Dec 30, 2022
20 Jan 9, 2023
7 Aug 6, 2021
1.8k Jan 3, 2023
0 Oct 20, 2021
2 Mar 24, 2022
2 Jul 16, 2022
2 Nov 18, 2022
269 Jul 23, 2022
17 Sep 12, 2022
2 Nov 19, 2021
5 Jan 25, 2022
106 Dec 25, 2022
6.2k Jan 4, 2023
5 Aug 27, 2019
92 Nov 16, 2022
1 Oct 27, 2021
15 Dec 27, 2022