Code Generator for Laravel - input OAS, output JSON-API
The ability to create a code generator for the API to save the future generation from the need to constantly create the same controllers, models, routers, middlewares, migrations, skeletons, filters, validations, etc. manually (even in the context of all the usual and convenient frameworks) seemed interesting to me.
I studied the typing and subtleties of the OpenAPI specification, I liked the linearity and the ability to describe the structure and types of any entity at 1-3 levels deep. Since at that time I was already familiar with Laravel (before it I used Yii2, CI, but they were less popular), as well as with the json-api data output format - the entire architecture settled down in the head with a connected graph.
')
Let's move on to the examples.
Suppose we have the following entity described in the OAS:
If we run the command
then we get the following generated objects:
1) Entity controller
He is already able to GET / POST / PATCH / DELETE, for which he will go to the table through the model, the migration for which will also be generated. DefaultController is always available to the developer, so that it is possible to implement functionality for all controllers.
2) Article Entity Model
As you can see, comments appeared here // >>> props >>> and // >>> methods >>> - they are needed to separate the code-space from the user code-space. There are also tag / topic relationships - belognsToMany / belongsTo respectively, which will associate the essence of the Article with tags / topics, providing an opportunity to access them in relations json-api with one GET request or modify them by updating the article.
3) Entity migration, with rollback support (reflection / atomicity):
The migration generator supports all types of indices (including composite ones).
4) Router for querying requests:
Roads were created not only for basic queries, but also relations (relations) with other entities that will be pulled out with 1 query and extensions as a bulk of operations for the ability to create / update / delete data in “batches”.
5) FormRequest for pre-processing / validating requests:
Everything is simple here - the rules of validation of properties and relations for the connection of the main entity with the entities in the relations method are generated.
Finally, the most pleasant are examples of requests:
Bring out the article, pull up in relations all its tags, pagination on page 2, with a limit of 10 and sort it in-time.
If we do not need to display all fields of the article:
Sort by multiple fields:
Filtering (or what falls in the WHERE clause):
An example of creating an entity (in this case, an article):
Answer:
See the link in links-> self? you can immediately
Returned a list of objects, in each of which the type of this object, its id, the whole set of attributes, then a link to itself, the relationships requested in the url via include = tag according to the specification there are no restrictions on the inclusion of relationships, that is, you can for example include = tag, The topic, city and all of them will be included in relationships , and their objects will be stored in included .
If we want to get 1 article and all its relations / links:
And here is an example of adding relationships to an already existing entity - a query:
Answer:
Console generator can pass additional options:
Thus, you report to the generator — create a code with migrations (you have already seen this) and regenerate the code, match it with the latest changes from the saved history, without affecting custom code areas, but only those that were generated automatically (i.e. which are highlighted with special blocks by comments in the code). It is possible to specify steps backwards, for example: --merge = 9 (rollback generation 9 steps back), the date of code generation in the past --merge = "2017-07-29 11:35:32" .
One of the library users suggested generating functional tests for queries - by adding the option - tests you can build tests to be sure that your API works without errors.
Additionally, you can use a variety of options (all of them are flexibly configured via the configurator, which lies in the generated module - example: /Modules/V2/Config/config.php ):
Naturally, all configurations can be point-on / off if necessary. For more information about the additional features of the code generator, see the links below. Contributions are always welcome.
Thank you for your attention, creative success.
Article Resources:
I studied the typing and subtleties of the OpenAPI specification, I liked the linearity and the ability to describe the structure and types of any entity at 1-3 levels deep. Since at that time I was already familiar with Laravel (before it I used Yii2, CI, but they were less popular), as well as with the json-api data output format - the entire architecture settled down in the head with a connected graph.
')
Let's move on to the examples.
Suppose we have the following entity described in the OAS:
ArticleAttributes: description: Article attributes description type: object properties: title: required: true type: string minLength: 16 maxLength: 256 facets: index: idx_title: index description: required: true type: string minLength: 32 maxLength: 1024 facets: spell_check: true spell_language: en url: required: false type: string minLength: 16 maxLength: 255 facets: index: idx_url: unique show_in_top: description: Show at the top of main page required: false type: boolean status: description: The state of an article enum: ["draft", "published", "postponed", "archived"] facets: state_machine: initial: ['draft'] draft: ['published'] published: ['archived', 'postponed'] postponed: ['published', 'archived'] archived: [] topic_id: description: ManyToOne Topic relationship required: true type: integer minimum: 1 maximum: 6 facets: index: idx_fk_topic_id: foreign references: id on: topic onDelete: cascade onUpdate: cascade rate: type: number minimum: 3 maximum: 9 format: double date_posted: type: date-only time_to_live: type: time-only deleted_at: type: datetime If we run the command
php artisan api:generate oas/openapi.yaml --migrations then we get the following generated objects:
1) Entity controller
<?php namespace Modules\V1\Http\Controllers; class ArticleController extends DefaultController { } He is already able to GET / POST / PATCH / DELETE, for which he will go to the table through the model, the migration for which will also be generated. DefaultController is always available to the developer, so that it is possible to implement functionality for all controllers.
2) Article Entity Model
<?php namespace Modules\V2\Entities; use Illuminate\Database\Eloquent\SoftDeletes; use rjapi\extension\BaseModel; class Article extends BaseModel { use SoftDeletes; // >>>props>>> protected $dates = ['deleted_at']; protected $primaryKey = 'id'; protected $table = 'article'; public $timestamps = false; public $incrementing = false; // <<<props<<< // >>>methods>>> public function tag() { return $this->belongsToMany(Tag::class, 'tag_article'); } public function topic() { return $this->belongsTo(Topic::class); } // <<<methods<<< } As you can see, comments appeared here // >>> props >>> and // >>> methods >>> - they are needed to separate the code-space from the user code-space. There are also tag / topic relationships - belognsToMany / belongsTo respectively, which will associate the essence of the Article with tags / topics, providing an opportunity to access them in relations json-api with one GET request or modify them by updating the article.
3) Entity migration, with rollback support (reflection / atomicity):
<?php use Illuminate\Support\Facades\Schema; use Illuminate\Database\Schema\Blueprint; use Illuminate\Database\Migrations\Migration; class CreateArticleTable extends Migration { public function up() { Schema::create('article', function(Blueprint $table) { $table->bigIncrements('id'); $table->string('title', 256); $table->index('title', 'idx_title'); $table->string('description', 1024); $table->string('url', 255); $table->unique('url', 'idx_url'); // Show at the top of main page $table->unsignedTinyInteger('show_in_top'); $table->enum('status', ["draft","published","postponed","archived"]); // ManyToOne Topic relationship $table->unsignedInteger('topic_id'); $table->foreign('topic_id', 'idx_fk_topic_id')->references('id')->on('topic')->onDelete('cascade')->onUpdate('cascade'); $table->timestamps(); }); } public function down() { Schema::dropIfExists('article'); } } The migration generator supports all types of indices (including composite ones).
4) Router for querying requests:
// >>>routes>>> // Article routes Route::group(['prefix' => 'v2', 'namespace' => 'Modules\\V2\\Http\\Controllers'], function() { // bulk routes Route::post('/article/bulk', 'ArticleController@createBulk'); Route::patch('/article/bulk', 'ArticleController@updateBulk'); Route::delete('/article/bulk', 'ArticleController@deleteBulk'); // basic routes Route::get('/article', 'ArticleController@index'); Route::get('/article/{id}', 'ArticleController@view'); Route::post('/article', 'ArticleController@create'); Route::patch('/article/{id}', 'ArticleController@update'); Route::delete('/article/{id}', 'ArticleController@delete'); // relation routes Route::get('/article/{id}/relationships/{relations}', 'ArticleController@relations'); Route::post('/article/{id}/relationships/{relations}', 'ArticleController@createRelations'); Route::patch('/article/{id}/relationships/{relations}', 'ArticleController@updateRelations'); Route::delete('/article/{id}/relationships/{relations}', 'ArticleController@deleteRelations'); }); // <<<routes<<< Roads were created not only for basic queries, but also relations (relations) with other entities that will be pulled out with 1 query and extensions as a bulk of operations for the ability to create / update / delete data in “batches”.
5) FormRequest for pre-processing / validating requests:
<?php namespace Modules\V1\Http\Requests; use rjapi\extension\BaseFormRequest; class ArticleFormRequest extends BaseFormRequest { // >>>props>>> public $id = null; // Attributes public $title = null; public $description = null; public $url = null; public $show_in_top = null; public $status = null; public $topic_id = null; public $rate = null; public $date_posted = null; public $time_to_live = null; public $deleted_at = null; // <<<props<<< // >>>methods>>> public function authorize(): bool { return true; } public function rules(): array { return [ 'title' => 'required|string|min:16|max:256|', 'description' => 'required|string|min:32|max:1024|', 'url' => 'string|min:16|max:255|', // Show at the top of main page 'show_in_top' => 'boolean', // The state of an article 'status' => 'in:draft,published,postponed,archived|', // ManyToOne Topic relationship 'topic_id' => 'required|integer|min:1|max:6|', 'rate' => '|min:3|max:9|', 'date_posted' => '', 'time_to_live' => '', 'deleted_at' => '', ]; } public function relations(): array { return [ 'tag', 'topic', ]; } // <<<methods<<< } Everything is simple here - the rules of validation of properties and relations for the connection of the main entity with the entities in the relations method are generated.
Finally, the most pleasant are examples of requests:
http://example.com/v1/article?include=tag&page=2&limit=10&sort=asc Bring out the article, pull up in relations all its tags, pagination on page 2, with a limit of 10 and sort it in-time.
If we do not need to display all fields of the article:
http://example.com/v1/article/1?include=tag&data=["title", "description"] Sort by multiple fields:
http://example.com/v1/article/1?include=tag&order_by={"title":"asc", "created_at":"desc"} Filtering (or what falls in the WHERE clause):
http://example.com/v1/article?include=tag&filter=[["updated_at", ">", "2018-01-03 12:13:13"], ["updated_at", "<", "2018-09-03 12:13:15"]] An example of creating an entity (in this case, an article):
POST http://laravel.loc/v1/article { "data": { "type":"article", "attributes": { "title":"Foo bar Foo bar Foo bar Foo bar", "description":"description description description description description", "fake_attr": "attr", "url":"title title bla bla bla", "show_in_top":1 } } } Answer:
{ "data": { "type": "article", "id": "1", "attributes": { "title": "Foo bar Foo bar Foo bar Foo bar", "description": "description description description description description", "url": "title title bla bla bla", "show_in_top": 1 }, "links": { "self": "laravel.loc/article/1" } } } See the link in links-> self? you can immediately
GET http://laravel.loc/article/1 or save it for future use. GET http://laravel.loc/v1/article?include=tag&filter=[["updated_at", ">", "2017-01-03 12:13:13"], ["updated_at", "<", "2019-01-03 12:13:15"]] { "data": [ { "type": "article", "id": "1", "attributes": { "title": "Foo bar Foo bar Foo bar Foo bar 1", "description": "The quick brovn fox jumped ower the lazy dogg", "url": "http://example.com/articles_feed 1", "show_in_top": 0, "status": "draft", "topic_id": 1, "rate": 5, "date_posted": "2018-02-12", "time_to_live": "10:11:12" }, "links": { "self": "laravel.loc/article/1" }, "relationships": { "tag": { "links": { "self": "laravel.loc/article/1/relationships/tag", "related": "laravel.loc/article/1/tag" }, "data": [ { "type": "tag", "id": "1" } ] } } } ], "included": [ { "type": "tag", "id": "1", "attributes": { "title": "Tag 1" }, "links": { "self": "laravel.loc/tag/1" } } ] } Returned a list of objects, in each of which the type of this object, its id, the whole set of attributes, then a link to itself, the relationships requested in the url via include = tag according to the specification there are no restrictions on the inclusion of relationships, that is, you can for example include = tag, The topic, city and all of them will be included in relationships , and their objects will be stored in included .
If we want to get 1 article and all its relations / links:
GET http://laravel.loc/v1/article/1?include=tag&data=["title", "description"] { "data": { "type": "article", "id": "1", "attributes": { "title": "Foo bar Foo bar Foo bar Foo bar 123456", "description": "description description description description description 123456", }, "links": { "self": "laravel.loc/article/1" }, "relationships": { "tag": { "links": { "self": "laravel.loc/article/1/relationships/tag", "related": "laravel.loc/article/1/tag" }, "data": [ { "type": "tag", "id": "3" }, { "type": "tag", "id": "1" }, { "type": "tag", "id": "2" } ] } } }, "included": [ { "type": "tag", "id": "3", "attributes": { "title": "Tag 4" }, "links": { "self": "laravel.loc/tag/3" } }, { "type": "tag", "id": "1", "attributes": { "title": "Tag 2" }, "links": { "self": "laravel.loc/tag/1" } }, { "type": "tag", "id": "2", "attributes": { "title": "Tag 3" }, "links": { "self": "laravel.loc/tag/2" } } ] } And here is an example of adding relationships to an already existing entity - a query:
PATCH http://laravel.loc/v1/article/1/relationships/tag { "data": { "type":"article", "id":"1", "relationships": { "tag": { "data": [{ "type": "tag", "id": "2" },{ "type": "tag", "id": "3" }] } } } } Answer:
{ "data": { "type": "article", "id": "1", "attributes": { "title": "Foo bar Foo bar Foo bar Foo bar 1", "description": "The quick brovn fox jumped ower the lazy dogg", "url": "http://example.com/articles_feed 1", "show_in_top": 0, "status": "draft", "topic_id": 1, "rate": 5, "date_posted": "2018-02-12", "time_to_live": "10:11:12" }, "links": { "self": "laravel.loc/article/1" }, "relationships": { "tag": { "links": { "self": "laravel.loc/article/1/relationships/tag", "related": "laravel.loc/article/1/tag" }, "data": [ { "type": "tag", "id": "2" }, { "type": "tag", "id": "3" } ] } } }, "included": [ { "type": "tag", "id": "2", "attributes": { "title": "Tag 2" }, "links": { "self": "laravel.loc/tag/2" } }, { "type": "tag", "id": "3", "attributes": { "title": "Tag 3" }, "links": { "self": "laravel.loc/tag/3" } } ] } Console generator can pass additional options:
php artisan api:generate oas/openapi.yaml --migrations --regenerate --merge=last Thus, you report to the generator — create a code with migrations (you have already seen this) and regenerate the code, match it with the latest changes from the saved history, without affecting custom code areas, but only those that were generated automatically (i.e. which are highlighted with special blocks by comments in the code). It is possible to specify steps backwards, for example: --merge = 9 (rollback generation 9 steps back), the date of code generation in the past --merge = "2017-07-29 11:35:32" .
One of the library users suggested generating functional tests for queries - by adding the option - tests you can build tests to be sure that your API works without errors.
Additionally, you can use a variety of options (all of them are flexibly configured via the configurator, which lies in the generated module - example: /Modules/V2/Config/config.php ):
<?php return [ 'name' => 'V2', 'query_params'=> [ // - 'limit' => 15, 'sort' => 'desc', 'access_token' => 'db7329d5a3f381875ea6ce7e28fe1ea536d0acaf', ], 'trees'=> [ // 'menu' => true, ], 'jwt'=> [ // jwt 'enabled' => true, 'table' => 'user', 'activate' => 30, 'expires' => 3600, ], 'state_machine'=> [ // finite state machine 'article'=> [ 'status'=> [ 'enabled' => true, 'states'=> [ 'initial' => ['draft'], 'draft' => ['published'], 'published' => ['archived', 'postponed'], 'postponed' => ['published', 'archived'], 'archived' => [''], ], ], ], ], 'spell_check'=> [ // 'article'=> [ 'description'=> [ 'enabled' => true, 'language' => 'en', ], ], ], 'bit_mask'=> [ // permissions ( true/false / ) 'user'=> [ 'permissions'=> [ 'enabled' => true, 'flags'=> [ 'publisher' => 1, 'editor' => 2, 'manager' => 4, 'photo_reporter' => 8, 'admin' => 16, ], ], ], ], 'cache'=> [ // 'tag'=> [ 'enabled' => false, // tag 'stampede_xfetch' => true, 'stampede_beta' => 1.1, 'ttl' => 3600, ], 'article'=> [ 'enabled' => true, // article 'stampede_xfetch' => true, 'stampede_beta' => 1.5, 'ttl' => 300, ], ], ]; Naturally, all configurations can be point-on / off if necessary. For more information about the additional features of the code generator, see the links below. Contributions are always welcome.
Thank you for your attention, creative success.
Article Resources:
Source: https://habr.com/ru/post/427741/
All Articles