cebe / yii2-app-api
Yii Framework Application Template for quickly building API-first applications.
Installs: 430
Dependents: 0
Suggesters: 0
Security: 0
Stars: 105
Watchers: 8
Forks: 10
Open Issues: 7
Type:project
Requires
- php: >=7.1.0
- php-openapi/yii2-openapi: ^2.0@beta
- yiisoft/yii2: ~2.0.16
- yiisoft/yii2-gii: ^2.1
Requires (Dev)
- codeception/codeception: ^4.2
- codeception/module-asserts: ^1.0.0
- codeception/module-db: ^1.2
- codeception/module-phpbrowser: ^1.0.0
- codeception/module-rest: ^1.0.0
- codeception/module-yii2: ^1.1
- roave/security-advisories: dev-latest
This package is auto-updated.
Last update: 2024-06-06 12:23:20 UTC
README
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 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
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 may use XDEBUGW=1
to enable xdebug for the webserver, e.g. make XDEBUGW=1 start
.
You can now continue with generating code.
Using Docker
You need Docker and Docker Compose installed.
Create the repository:
composer create-project php-openapi/yii2-app-api my-api
For the easiest way you need GNU make, then run:
make start-docker
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:
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'
Generate Code
At this point you can start generating your API code to play with it by following the instructions below. If you'd like to start a real project instead of just playing around you can find more detailed documentation in docs/README.md specifically the "Getting Started"-Section.
Console
Tip: If you use Docker, run
make cli
before 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
Note: If the OpenAPI spec file is present locally on the file system, then
openApiPath
must be specified as an absolute path, relative paths will not work correctly. On UNIX based OS it must start with/
. Example:/home/user/documents/MyProjectOpenAPISpec.yml
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."
},
...
]
Linting the OpenAPI specification
You can run a linter to check the validity of your OpenAPI specification file:
make lint-js # run spectral lint
make lint-php # run php-openapi validate
make lint # run both of the above commands
You can find more information on spectral at https://www.npmjs.com/package/@stoplight/spectral-cli#-documentation-and-community.
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 (yii
command).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
Development
Below commands are helpful while developing this project:
./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
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.:cloud: "Your Professional Deployment Platform".