Laravel के लिए कोड जनरेटर - OAS इनपुट के लिए, JSON-API आउटपुट के लिए

भावी पीढ़ी को लगातार एक ही नियंत्रक, मॉडल, राउटर, मिडलवेयर, माइग्रेशन, कंकाल, फिल्टर, सत्यापन आदि बनाने की आवश्यकता से बचाने के लिए एपीआई के लिए एक कोड जनरेटर बनाने की क्षमता। मैन्युअल रूप से (यहां तक ​​कि परिचित और सुविधाजनक फ्रेमवर्क के संदर्भ में), यह मुझे दिलचस्प लगा।

मैंने ओपनएपीआई विनिर्देश के प्रकार और बारीकियों का अध्ययन किया, मुझे इसकी रैखिकता और किसी भी इकाई की संरचना और प्रकार का वर्णन करने की क्षमता 1-3 स्तरों पर गहरी पसंद आई। चूंकि उस समय मैं पहले से ही लारवेल से परिचित था (Yii2 का उपयोग सीआई से पहले किया गया था, लेकिन वे कम लोकप्रिय थे), साथ ही साथ json-api डेटा आउटपुट प्रारूप - पूरी वास्तुकला एक जुड़े हुए ग्राफ के साथ मेरे सिर में नीचे चली गई।



चलिए उदाहरणों पर चलते हैं।

मान लें कि हमारे पास 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 

अगर हम कमांड चलाते हैं

 php artisan api:generate oas/openapi.yaml --migrations 

तब हमें निम्नलिखित उत्पन्न वस्तुएँ मिलती हैं:

1) इकाई नियंत्रक

 <?php namespace Modules\V1\Http\Controllers; class ArticleController extends DefaultController { } 

वह पहले से ही GET / POST / PATCH / DELETE जानता है, जिसके लिए वह मॉडल के माध्यम से टेबल पर जाएगा, जिसके लिए माइग्रेशन भी जेनरेट होगा। DefaultController हमेशा डेवलपर के लिए उपलब्ध है, ताकि सभी नियंत्रकों के लिए कार्यक्षमता को लागू करना संभव हो।

2) अनुच्छेद इकाई मॉडल

 <?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<<< } 

जैसा कि आप देख सकते हैं, टिप्पणियाँ यहाँ दिखाई दीं >> >>> props >>> और // >>> विधियाँ >>> - कोड-स्पेस को उपयोगकर्ता कोड-स्पेस से अलग करने के लिए इनकी आवश्यकता होती है। एक टैग / विषय संबंध भी है - belognsToMany / अंतर्गत। क्रमशः, जो अनुच्छेद इकाई को टैग / विषयों के साथ जोड़ देगा, उन्हें एक ही GET अनुरोध के साथ संबंधों json-api में उपयोग करने या उन्हें लेख को अपडेट करने के लिए बदलने का अवसर प्रदान करेगा।

3) रोलबैक समर्थन (प्रतिबिंब / परमाणु) के साथ इकाई प्रवासन:

 <?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'); } } 

माइग्रेशन जनरेटर सभी प्रकार के अनुक्रमित (समग्र वाले सहित) का समर्थन करता है।

4) स्क्रॉलिंग अनुरोधों के लिए राउटर:

 // >>>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<<< 

रूट को न केवल बुनियादी प्रश्नों के लिए बनाया गया था, बल्कि अन्य संस्थाओं के साथ भी संबंध थे, जो 1 क्वेरी और एक्सटेंशन द्वारा बल्क में डेटा बनाने / अपडेट करने / हटाने की क्षमता के लिए बल्क ऑपरेशन के रूप में खींचे जाएंगे।

5) पूर्व-प्रसंस्करण / अनुरोधों के सत्यापन के लिए औपचारिक रूप:

 <?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<<< } 

यहां सब कुछ सरल है - संबंधों की पद्धति में संस्थाओं के साथ मुख्य इकाई को जोड़ने के लिए गुणों और संबंधों को मान्य करने के नियम उत्पन्न होते हैं।

अंत में, सबसे अच्छा हिस्सा क्वेरी उदाहरण है:

 http://example.com/v1/article?include=tag&page=2&limit=10&sort=asc 

एक लेख प्रदर्शित करें, संबंधों में इसके सभी टैगों को कस लें, पृष्ठ 2 पर पेजेशन, 10 की सीमा के साथ, और उम्र के अनुसार क्रमबद्ध करें।

अगर हमें लेख के सभी क्षेत्रों को प्रदर्शित करने की आवश्यकता नहीं है:

 http://example.com/v1/article/1?include=tag&data=["title", "description"] 

कई क्षेत्रों द्वारा क्रमबद्ध करें:

 http://example.com/v1/article/1?include=tag&order_by={"title":"asc", "created_at":"desc"} 

फ़िल्टरिंग (या जो भी वहाँ स्थित है):

 http://example.com/v1/article?include=tag&filter=[["updated_at", ">", "2018-01-03 12:13:13"], ["updated_at", "<", "2018-09-03 12:13:15"]] 

एक इकाई बनाने का एक उदाहरण (इस मामले में, लेख):

 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 } } } 

उत्तर है:

 { "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" } } } 

लिंक में लिंक देखें-> स्व? आप तुरंत कर सकते हैं

 GET http://laravel.loc/article/1 

या इसे भविष्य के संदर्भ के लिए सहेजें।

 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" } } ] } 

उन्होंने वस्तुओं की एक सूची लौटा दी, जिनमें से प्रत्येक में इस वस्तु का प्रकार, इसकी आईडी, विशेषताओं का पूरा सेट, फिर स्वयं के लिए एक लिंक, यूआरएल के माध्यम से अनुरोध किए गए संबंधों में = टैग शामिल हैं, विनिर्देश के अनुसार, संबंधों पर कोई प्रतिबंध नहीं है, उदाहरण के लिए, = = टैग शामिल हैं। विषय, शहर और उन सभी को रिश्ते ब्लॉक में शामिल किया जाएगा, और उनकी वस्तुओं को शामिल किया जाएगा।

यदि हम 1 लेख और उसके सभी रिश्तों / रिश्तों को प्राप्त करना चाहते हैं:

 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" } } ] } 

और यहाँ एक मौजूदा संस्था से रिश्तों को जोड़ने का एक उदाहरण है - एक अनुरोध:

 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" }] } } } } 

उत्तर है:

 { "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" } } ] } 

आप कंसोल जनरेटर के लिए अतिरिक्त विकल्प स्थानांतरित कर सकते हैं:

 php artisan api:generate oas/openapi.yaml --migrations --regenerate --merge=last 

इस प्रकार, आप जनरेटर को बताते हैं - माइग्रेशन के साथ एक कोड बनाएं (आपने पहले ही इसे देखा था) और कोड को फिर से जेनरेट करें, इसे सहेजे गए इतिहास से नवीनतम परिवर्तनों के साथ संग्रहीत करते हुए, कोड के कस्टम सेक्शन को प्रभावित किए बिना, लेकिन केवल वे जो स्वचालित रूप से उत्पन्न हुए थे (बस, उन) , जो कोड में टिप्पणियों के साथ विशेष ब्लॉकों द्वारा हाइलाइट किए गए हैं)। उदाहरण के लिए, चरण वापस निर्दिष्ट करना संभव है: --merge = 9 (पीढ़ी 9 कदम पीछे रोल करें), कोड पीढ़ी अतीत में दिनांक --merge = "2017-07-29 11:35:32" ।

लाइब्रेरी के उपयोगकर्ताओं में से एक ने प्रश्नों के लिए कार्यात्मक परीक्षण उत्पन्न करने का सुझाव दिया - - theests विकल्प जोड़कर आप यह सुनिश्चित करने के लिए परीक्षण चला सकते हैं कि आपकी API त्रुटियों के साथ काम करती है।

इसके अतिरिक्त, आप कई विकल्पों का उपयोग कर सकते हैं (वे सभी लचीले रूप से विन्यासकर्ता के माध्यम से कॉन्फ़िगर किए गए हैं, जो उत्पन्न मॉड्यूल में निहित है - उदाहरण: /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, ], ], ]; 

स्वाभाविक रूप से, सभी कॉन्फ़िगरेशन आवश्यक होने पर / बंद बिंदु हो सकते हैं। कोड जनरेटर की अतिरिक्त विशेषताओं के बारे में अधिक जानकारी के लिए, नीचे दिए गए लिंक देखें। योगदानों का हमेशा स्वागत है।

आपका ध्यान, रचनात्मक सफलता के लिए धन्यवाद।

लेख संसाधन:

• जनक
• json-api विनिर्देशन
• OAS विनिर्देशन