Stars: 102
Forks: 10
Pull Requests: 6
Issues: 13
Watchers: 7
Last Updated: 2023-07-10 17:58:05
OpenAPI Spec to API in 3, 2, 1... done!
License: MIT License
Languages: PHP, Makefile, Dockerfile
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).
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.
There are two different ways:
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 may use XDEBUGW=1
to enable xdebug for the webserver, e.g. make XDEBUGW=1 start
.
You can now continue with generating code.
You need Docker and Docker Compose installed.
Create the repository:
composer create-project cebe/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'
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.
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
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
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."
},
...
]
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 tier
config/
- configuration for API tier
url-rules.php
- custom URL rulesurl-rules.rest.php
- URL rules generated from OpenAPI Descriptioncomponents.php
- application componentsapp.php
- Yii application config (+ overrides for different environments app-*.php
)controllers/
- Controller classes generated from OpenAPI Descriptionweb/
- public web directory for API applicationbackend/
- Backend application tier
config/
- configuration for Backend tier
components.php
- application componentsapp.php
- Yii application config (+ overrides for different environments app-*.php
)controllers/
- Controller classesviews/
- View filesweb/
- public web directory for Backend applicationcommon/
- common code files
models/
- model classes generated from OpenAPI Descriptionmigrations/
- database migrations generated from OpenAPI Descriptionconfig/
- Common configuration for all application tiers
components.php
- Yii application components (+ overrides for different environments components-*.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 for Yii::$app->params
console/
- Console application tier
config/
- configuration for Console tier
components.php
- application componentsapp.php
- Yii application config (+ overrides for different environments app-*.php
)logs/
- log files
runtime/
- temporary runtime files
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
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.☁️ "Your Professional Deployment Platform".