Skip to content

Commit b6920d6

Browse files
GautierDeleGautierDele
authored
Merge pull request #64 from Lomkit/feature/documentation
Feature/documentation
2 parents 8c2fa62 + 96b9999 commit b6920d6

File tree

6 files changed

+236
-68
lines changed

6 files changed

+236
-68
lines changed

‎src/Console/Commands/DocumentationCommand.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ public function handle()
4343
$path,
4444
json_encode($openApi->jsonSerialize())
4545
);
46+
47+
$this->info('The documentation was generated successfully!');
48+
$this->info('Open '.url(config('rest.documentation.routing.path')).'in a web browser.');
4649
}
4750

4851
/**

‎src/Console/Commands/DocumentationProviderCommand.php‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
<?php
2+
3+
namespace Lomkit\Rest\Console\Commands;
4+
5+
use Illuminate\Console\GeneratorCommand;
6+
use Illuminate\Contracts\Console\PromptsForMissingInput;
7+
use Lomkit\Rest\Console\ResolvesStubPath;
8+
9+
class DocumentationProviderCommand extends GeneratorCommand implements PromptsForMissingInput
10+
{
11+
use ResolvesStubPath;
12+
13+
/**
14+
* The console command signature.
15+
*
16+
* @var string
17+
*/
18+
protected $signature = 'rest:documentation-provider {name=RestDocumentationServiceProvider : The name of the service provider}
19+
{--path= : The location where the service provider file should be created}';
20+
21+
/**
22+
* The type of class being generated.
23+
*
24+
* @var string
25+
*/
26+
protected $type = 'Service provider';
27+
28+
/**
29+
* The console command description.
30+
*
31+
* @var string
32+
*/
33+
protected $description = 'Create the documentation service provider class';
34+
35+
/**
36+
* Get the stub file for the generator.
37+
*
38+
* @return string
39+
*/
40+
protected function getStub()
41+
{
42+
return $this->resolveStubPath('/stubs/rest/rest-documentation-service-provider.stub');
43+
}
44+
45+
/**
46+
* Get the path where the action file should be created.
47+
*
48+
* @param string $name
49+
*
50+
* @return string
51+
*/
52+
protected function getPath($name)
53+
{
54+
if (!is_null($this->option('path'))) {
55+
return $this->option('path').'/'.$this->argument('name').'.php';
56+
}
57+
58+
return parent::getPath($name);
59+
}
60+
61+
/**
62+
* Get the default namespace for the class.
63+
*
64+
* @param string $rootNamespace
65+
*
66+
* @return string
67+
*/
68+
protected function getDefaultNamespace($rootNamespace)
69+
{
70+
return $rootNamespace.'\Providers';
71+
}
72+
73+
/**
74+
* Get the default namespace for the class.
75+
*
76+
* @return string
77+
*/
78+
protected function getResourceNamespace()
79+
{
80+
$rootNamespace = $this->laravel->getNamespace();
81+
82+
return is_dir(app_path('Providers')) ? $rootNamespace.'Providers\\' : $rootNamespace;
83+
}
84+
}

‎src/Console/stubs/rest-documentation-service-provider.stub‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<?php
2+
3+
namespace {{ namespace }};
4+
5+
use Illuminate\Support\ServiceProvider;
6+
use Lomkit\Rest\Documentation\Schemas\OpenAPI;
7+
use Lomkit\Rest\Documentation\Schemas\Operation;
8+
use Lomkit\Rest\Documentation\Schemas\Path;
9+
use Lomkit\Rest\Facades\Rest;
10+
11+
class RestDocumentationServiceProvider extends ServiceProvider
12+
{
13+
/**
14+
* Register any application services.
15+
*
16+
* @return void
17+
*/
18+
public function register()
19+
{
20+
//
21+
}
22+
23+
/**
24+
* Bootstrap any application services.
25+
*
26+
* @return void
27+
*/
28+
public function boot()
29+
{
30+
Rest::withDocumentationCallback(function (OpenAPI $openAPI) {
31+
$openAPI->withPaths(
32+
[
33+
'myPath' => (new Path)
34+
->withDescription('my custom path')
35+
->withGet(
36+
(new Operation)
37+
->withTags(['Callable'])
38+
->withSummary('You should call this !')
39+
)
40+
]
41+
);
42+
return $openAPI;
43+
});
44+
}
45+
}

‎src/Documentation/Schemas/RequestBody.php‎

Lines changed: 95 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
namespace Lomkit\Rest\Documentation\Schemas;
44

55
use Lomkit\Rest\Http\Controllers\Controller;
6+
use Lomkit\Rest\Http\Requests\RestRequest;
7+
use Lomkit\Rest\Instructions\Instruction;
8+
use Lomkit\Rest\Relations\Relation;
69

710
class RequestBody extends Schema
811
{
@@ -103,9 +106,9 @@ public function required(): bool
103106
/**
104107
* Generate and return the request body schema.
105108
*
106-
* @return Schema
109+
* @return RequestBody
107110
*/
108-
public function generate(): Schema
111+
public function generate(): RequestBody
109112
{
110113
return $this;
111114
}
@@ -133,6 +136,8 @@ public function jsonSerialize(): mixed
133136
*/
134137
public function generateSearch(Controller $controller): RequestBody
135138
{
139+
$request = app()->make(RestRequest::class);
140+
136141
return $this
137142
->withContent(
138143
[
@@ -141,61 +146,83 @@ public function generateSearch(Controller $controller): RequestBody
141146
(new Example())
142147
->withValue(
143148
[
144-
'scopes' => [
145-
['name' => 'withTrashed', 'parameters' => [true]],
146-
],
147-
'filters' => [
148-
['field' => 'id', 'operator' => '>', 'value' => 1, 'type' => 'or'],
149-
['nested' => [
150-
['field' => 'user.id', 'operator' => '<', 'value' => 2],
151-
['field' => 'id', 'operator' => '>', 'value' => 100, 'type' => 'or'],
152-
]],
153-
],
154-
'sorts' => [
155-
['field' => 'user_id', 'direction' => 'desc'],
156-
['field' => 'id', 'direction' => 'asc'],
157-
],
158-
'selects' => [
159-
['field' => 'id'],
160-
],
161-
'includes' => [
149+
'search' => array_merge(
150+
// Scopes
162151
[
163-
'relation' => 'posts',
164-
'filters' => [
165-
['field' => 'id', 'operator' => 'in', 'value' => [1, 3]],
166-
],
167-
'limit' => 2,
152+
'scopes' => collect($controller::newResource()->getScopes($request))
153+
->map(function ($scope) {
154+
return ['name' => $scope, 'parameters' => []];
155+
})
156+
->toArray(),
168157
],
169-
],
170-
'aggregates' => [
158+
// Filters
171159
[
172-
'relation' => 'stars',
173-
'type' => 'max',
174-
'field' => 'rate',
175-
'filters' => [
176-
[
177-
'name' => 'type',
178-
'value' => 'odd',
179-
],
180-
],
160+
'filters' => collect($controller::newResource()->getFields($request))
161+
->map(function ($filter) {
162+
return ['field' => $filter, 'operator' => '=', 'value' => ''];
163+
})
164+
->toArray(),
181165
],
182-
],
183-
'instructions' => [
166+
// Sorts
167+
[
168+
'sorts' => collect($controller::newResource()->getFields($request))
169+
->map(function ($sort) {
170+
return ['field' => $sort, 'direction' => 'desc'];
171+
})
172+
->toArray(),
173+
],
174+
// Selects
175+
[
176+
'selects' => collect($controller::newResource()->getFields($request))
177+
->map(function ($select) {
178+
return ['field' => $select];
179+
})
180+
->toArray(),
181+
],
182+
// Includes
183+
[
184+
'includes' => collect($controller::newResource()->getRelations($request))
185+
->map(function (Relation $relation) {
186+
return ['relation' => $relation->relation];
187+
})
188+
->toArray(),
189+
],
190+
// Aggregates
191+
[
192+
'aggregates' => [],
193+
],
194+
// Instructions
195+
[
196+
'instructions' => collect($controller::newResource()->getInstructions($request))
197+
->map(function (Instruction $instruction) use ($request) {
198+
return [
199+
'name' => $instruction->name(),
200+
'fields' => collect($instruction->fields($request))
201+
->map(function ($field) {
202+
return ['field' => $field, 'value' => ''];
203+
})
204+
->toArray(),
205+
];
206+
})
207+
->toArray(),
208+
],
209+
// Gates
184210
[
185-
'name' => 'odd-even-id',
186-
'fields' => [
187-
[
188-
'name' => 'type',
189-
'value' => 'odd',
190-
],
211+
'gates' => [
212+
'create',
213+
'update',
214+
'delete',
191215
],
192216
],
193-
],
194-
'gates' => [
195-
'create',
196-
],
197-
'page' => 2,
198-
'limit' => 10,
217+
// Page
218+
[
219+
'page' => 1,
220+
],
221+
// Limit
222+
[
223+
'limit' => $controller::newResource()->getLimits($request)[0],
224+
]
225+
),
199226
]
200227
)
201228
->generate()
@@ -215,6 +242,8 @@ public function generateSearch(Controller $controller): RequestBody
215242
*/
216243
public function generateMutate(Controller $controller): RequestBody
217244
{
245+
$request = app()->make(RestRequest::class);
246+
218247
return $this
219248
->withContent(
220249
[
@@ -226,25 +255,23 @@ public function generateMutate(Controller $controller): RequestBody
226255
'mutate' => [
227256
[
228257
'operation' => 'create',
229-
'attributes' => ['email' => '[email protected]'],
230-
'relations' => [
231-
'star' => [
232-
'operation' => 'create',
233-
'attributes' => ['number' => 2],
234-
],
235-
],
258+
// Attributes
259+
'attributes' => collect($controller::newResource()->getFields($request))
260+
->mapWithKeys(function ($field) {
261+
return [$field => ''];
262+
})
263+
->toArray(),
264+
// Relations
265+
'relations' => collect($controller::newResource()->getRelations($request))
266+
->mapWithKeys(function (Relation $relation) {
267+
return [$relation->relation => [
268+
'operation' => 'update',
269+
'key' => 1,
270+
]];
271+
})
272+
->toArray(),
236273
],
237-
[
238-
'operation' => 'update',
239-
'key' => 1,
240-
'attributes' => ['email' => '[email protected]'],
241-
'relations' => [
242-
'star' => [
243-
'operation' => 'detach',
244-
'key' => 1,
245-
],
246-
],
247-
]],
274+
],
248275
]
249276
)
250277
->generate()

‎src/RestServiceProvider.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
use Lomkit\Rest\Console\Commands\BaseResourceCommand;
1010
use Lomkit\Rest\Console\Commands\ControllerCommand;
1111
use Lomkit\Rest\Console\Commands\DocumentationCommand;
12+
use Lomkit\Rest\Console\Commands\DocumentationProviderCommand;
1213
use Lomkit\Rest\Console\Commands\InstructionCommand;
1314
use Lomkit\Rest\Console\Commands\QuickStartCommand;
1415
use Lomkit\Rest\Console\Commands\ResourceCommand;
@@ -95,6 +96,7 @@ protected function registerCommands()
9596
ActionCommand::class,
9697
InstructionCommand::class,
9798
DocumentationCommand::class,
99+
DocumentationProviderCommand::class,
98100
]);
99101
}
100102
}

‎tests/Feature/Commands/DocumentationCommandTest.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,11 @@ public function test_create_documentation_class(): void
1212

1313
$this->assertFileExists('./.phpunit.cache/openapi.json');
1414
}
15+
16+
public function test_create_documentation_service_provider_class(): void
17+
{
18+
$this->artisan('rest:documentation-provider', ['--path' => './.phpunit.cache'])->assertOk();
19+
20+
$this->assertFileExists('./.phpunit.cache/RestDocumentationServiceProvider.php');
21+
}
1522
}

0 commit comments

Comments
 (0)