Home

Awesome

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).

Latest Stable Version Total Downloads License

Demo

asciicast

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:

  1. Setup
  2. Generate Code

More Docs and Guides can be found in /docs.

Setup <span id="setup"></span>

There are two different ways:

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 <span id="generate-code"></span>

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.

Gii - 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":

Gii - REST API Generator - Generated files

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 <span id="structure"></span>

This application template consists of 3 application tiers:

The following list explains the directory structure in more detail:

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".