Skip to content

Commit eef31df

Browse files
dunglasdunglas
committed
Improve Swagger's DocumentationNormalizer
1 parent 399d4b3 commit eef31df

File tree

1 file changed

+105
-190
lines changed

1 file changed

+105
-190
lines changed

‎src/Swagger/Serializer/DocumentationNormalizer.php‎

Lines changed: 105 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -130,197 +130,113 @@ private function getPath(string $resourceShortName, array $operation, bool $coll
130130
private function getPathOperation(string $operationName, array $operation, string $method, bool $collection, ResourceMetadata $resourceMetadata, array $mimeTypes) : \ArrayObject
131131
{
132132
$pathOperation = new \ArrayObject($operation['swagger_context'] ?? []);
133-
134133
$resourceShortName = $resourceMetadata->getShortName();
134+
$pathOperation['tags'] ?? $pathOperation['tags'] = [$resourceShortName];
135+
$pathOperation['operationId'] ?? $pathOperation['operationId'] = sprintf('%s%s%s', lcfirst($operationName), ucfirst($resourceShortName), ucfirst($collection ? 'collection' : 'item'));
136+
137+
if ('GET' === $method) {
138+
$pathOperation['produces'] ?? $pathOperation['produces'] = $mimeTypes;
139+
140+
if ($collection) {
141+
$pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves the collection of %s resources.', $resourceShortName);
142+
$pathOperation['responses'] ?? $pathOperation['responses'] = [
143+
'200' => [
144+
'description' => sprintf('%s collection response', $resourceShortName),
145+
'schema' => [
146+
'type' => 'array',
147+
'items' => ['$ref' => sprintf('#/definitions/%s', $resourceShortName)],
148+
],
149+
],
150+
];
151+
152+
return $pathOperation;
153+
}
135154

136-
if (!isset($pathOperation['tags'])) {
137-
$pathOperation['tags'] = [
138-
$resourceShortName,
155+
$pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves a %s resource.', $resourceShortName);
156+
$pathOperation['parameters'] ?? $pathOperation['parameters'] = [[
157+
'name' => 'id',
158+
'in' => 'path',
159+
'required' => true,
160+
'type' => 'integer',
161+
]];
162+
$pathOperation['responses'] ?? $pathOperation['responses'] = [
163+
'200' => [
164+
'description' => sprintf('%s resource response', $resourceShortName),
165+
'schema' => ['$ref' => sprintf('#/definitions/%s', $resourceShortName)],
166+
],
167+
'404' => ['description' => 'Resource not found'],
139168
];
140-
}
141169

142-
if (!isset($pathOperation['operationId'])) {
143-
$pathOperation['operationId'] = sprintf('%s%s%s', lcfirst($operationName), ucfirst($resourceShortName), ucfirst($collection ? 'collection' : 'item'));
170+
return $pathOperation;
144171
}
145172

146-
switch ($method) {
147-
case 'GET':
148-
if (!isset($pathOperation['produces'])) {
149-
$pathOperation['produces'] = $mimeTypes;
150-
}
151-
152-
if ($collection) {
153-
if (!isset($pathOperation['summary'])) {
154-
$pathOperation['summary'] = sprintf('Retrieves the collection of %s resources.', $resourceShortName);
155-
}
156-
157-
if (!isset($pathOperation['responses'])) {
158-
$pathOperation['responses'] = [
159-
'200' => [
160-
'description' => sprintf('%s collection response', $resourceShortName),
161-
'schema' => [
162-
'type' => 'array',
163-
'items' => [
164-
'$ref' => sprintf('#/definitions/%s', $resourceShortName),
165-
],
166-
],
167-
],
168-
];
169-
}
170-
} else {
171-
if (!isset($pathOperation['summary'])) {
172-
$pathOperation['summary'] = sprintf('Retrieves a %s resource.', $resourceShortName);
173-
}
174-
175-
if (!isset($pathOperation['parameters'])) {
176-
$pathOperation['parameters'] = [
177-
[
178-
'name' => 'id',
179-
'in' => 'path',
180-
'required' => true,
181-
'type' => 'integer',
182-
],
183-
];
184-
}
185-
186-
if (!isset($pathOperation['responses'])) {
187-
$pathOperation['responses'] = [
188-
'200' => [
189-
'description' => sprintf('%s resource response', $resourceShortName),
190-
'schema' => [
191-
'$ref' => sprintf('#/definitions/%s', $resourceShortName),
192-
],
193-
],
194-
'404' => [
195-
'description' => 'Resource not found',
196-
],
197-
];
198-
}
199-
}
200-
break;
201-
202-
case 'POST':
203-
if (!isset($pathOperation['consumes'])) {
204-
$pathOperation['consumes'] = $mimeTypes;
205-
}
206-
if (!isset($pathOperation['produces'])) {
207-
$pathOperation['produces'] = $mimeTypes;
208-
}
209-
210-
if (!isset($pathOperation['summary'])) {
211-
$pathOperation['summary'] = sprintf('Creates a %s resource.', $resourceShortName);
212-
}
213-
214-
if (!isset($pathOperation['parameters'])) {
215-
$pathOperation['parameters'] = [
216-
[
217-
'name' => lcfirst($resourceShortName),
218-
'in' => 'body',
219-
'description' => sprintf('The new %s resource', $resourceShortName),
220-
'schema' => [
221-
'$ref' => sprintf('#/definitions/%s', $resourceShortName),
222-
],
223-
],
224-
];
225-
}
226-
227-
if (!isset($pathOperation['responses'])) {
228-
$pathOperation['responses'] = [
229-
'201' => [
230-
'description' => sprintf('%s resource created', $resourceShortName),
231-
'schema' => [
232-
'$ref' => sprintf('#/definitions/%s', $resourceShortName),
233-
],
234-
],
235-
'400' => [
236-
'description' => 'Invalid input',
237-
],
238-
'404' => [
239-
'description' => 'Resource not found',
240-
],
241-
];
242-
}
243-
break;
244-
245-
case 'PUT':
246-
if (!isset($pathOperation['consumes'])) {
247-
$pathOperation['consumes'] = $mimeTypes;
248-
}
249-
if (!isset($pathOperation['produces'])) {
250-
$pathOperation['produces'] = $mimeTypes;
251-
}
252-
253-
if (!isset($pathOperation['summary'])) {
254-
$pathOperation['summary'] = sprintf('Replaces the %s resource.', $resourceShortName);
255-
}
173+
if ('POST' === $method) {
174+
$pathOperation['consumes'] ?? $pathOperation['consumes'] = $mimeTypes;
175+
$pathOperation['produces'] ?? $pathOperation['produces'] = $mimeTypes;
176+
$pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Creates a %s resource.', $resourceShortName);
177+
$pathOperation['parameters'] ?? $pathOperation['parameters'] = [[
178+
'name' => lcfirst($resourceShortName),
179+
'in' => 'body',
180+
'description' => sprintf('The new %s resource', $resourceShortName),
181+
'schema' => ['$ref' => sprintf('#/definitions/%s', $resourceShortName)],
182+
]];
183+
$pathOperation['responses'] ?? $pathOperation['responses'] = [
184+
'201' => [
185+
'description' => sprintf('%s resource created', $resourceShortName),
186+
'schema' => ['$ref' => sprintf('#/definitions/%s', $resourceShortName)],
187+
],
188+
'400' => ['description' => 'Invalid input'],
189+
'404' => ['description' => 'Resource not found'],
190+
];
256191

257-
if (!isset($pathOperation['parameters'])) {
258-
$pathOperation['parameters'] = [
259-
[
260-
'name' => 'id',
261-
'in' => 'path',
262-
'type' => 'integer',
263-
'required' => true,
264-
],
265-
[
266-
'name' => lcfirst($resourceShortName),
267-
'in' => 'body',
268-
'description' => sprintf('The updated %s resource', $resourceShortName),
269-
'schema' => [
270-
'$ref' => sprintf('#/definitions/%s', $resourceShortName),
271-
],
272-
],
273-
];
274-
}
192+
return $pathOperation;
193+
}
275194

276-
if (!isset($pathOperation['responses'])) {
277-
$pathOperation['responses'] = [
278-
'200' => [
279-
'description' => sprintf('%s resource updated', $resourceShortName),
280-
'schema' => [
281-
'$ref' => sprintf('#/definitions/%s', $resourceShortName),
282-
],
283-
],
284-
'400' => [
285-
'description' => 'Invalid input',
286-
],
287-
'404' => [
288-
'description' => 'Resource not found',
289-
],
290-
];
291-
}
292-
break;
195+
if ($method === 'PUT') {
196+
$pathOperation['consumes'] ?? $pathOperation['consumes'] = $mimeTypes;
197+
$pathOperation['produces'] ?? $pathOperation['produces'] = $mimeTypes;
198+
$pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Replaces the %s resource.', $resourceShortName);
199+
$pathOperation['parameters'] ?? $pathOperation['parameters'] = [
200+
[
201+
'name' => 'id',
202+
'in' => 'path',
203+
'type' => 'integer',
204+
'required' => true,
205+
],
206+
[
207+
'name' => lcfirst($resourceShortName),
208+
'in' => 'body',
209+
'description' => sprintf('The updated %s resource', $resourceShortName),
210+
'schema' => ['$ref' => sprintf('#/definitions/%s', $resourceShortName)],
211+
],
212+
];
213+
$pathOperation['responses'] ?? $pathOperation['responses'] = [
214+
'200' => [
215+
'description' => sprintf('%s resource updated', $resourceShortName),
216+
'schema' => ['$ref' => sprintf('#/definitions/%s', $resourceShortName)],
217+
],
218+
'400' => ['description' => 'Invalid input'],
219+
'404' => ['description' => 'Resource not found'],
220+
];
293221

294-
case 'DELETE':
295-
if (!isset($pathOperation['summary'])) {
296-
$pathOperation['summary'] = sprintf('Removes the %s resource.', $resourceShortName);
297-
}
222+
return $pathOperation;
223+
}
298224

299-
if (!isset($pathOperation['responses'])) {
300-
$pathOperation['responses'] = [
301-
'204' => [
302-
'description' => sprintf('%s resource deleted', $resourceShortName),
303-
],
304-
'404' => [
305-
'description' => 'Resource not found',
306-
],
307-
];
308-
}
225+
if ($method === 'DELETE') {
226+
$pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Removes the %s resource.', $resourceShortName);
227+
$pathOperation['responses'] ?? $pathOperation['responses'] = [
228+
'204' => ['description' => sprintf('%s resource deleted', $resourceShortName)],
229+
'404' => ['description' => 'Resource not found'],
230+
];
309231

310-
if (!isset($pathOperation['parameters'])) {
311-
$pathOperation['parameters'] = [
312-
[
313-
'name' => 'id',
314-
'in' => 'path',
315-
'type' => 'integer',
316-
'required' => true,
317-
],
318-
];
319-
}
320-
break;
232+
$pathOperation['parameters'] ?? $pathOperation['parameters'] = [[
233+
'name' => 'id',
234+
'in' => 'path',
235+
'type' => 'integer',
236+
'required' => true,
237+
]];
321238

322-
default:
323-
break;
239+
return $pathOperation;
324240
}
325241

326242
return $pathOperation;
@@ -338,29 +254,30 @@ private function getPathOperation(string $operationName, array $operation, strin
338254
*/
339255
private function getDefinitionSchema(string $resourceClass, ResourceMetadata $resourceMetadata) : \ArrayObject
340256
{
341-
$definitionSchema = new \ArrayObject([
342-
'type' => 'object',
343-
]);
257+
$definitionSchema = new \ArrayObject(['type' => 'object']);
344258

345-
if ($description = $resourceMetadata->getDescription()) {
259+
if (null !== $description = $resourceMetadata->getDescription()) {
346260
$definitionSchema['description'] = $description;
347261
}
348262

349-
if ($iri = $resourceMetadata->getIri()) {
263+
if (null !== $iri = $resourceMetadata->getIri()) {
350264
$definitionSchema['externalDocs'] = [
351265
'url' => $iri,
352266
];
353267
}
354268

355269
$attributes = $resourceMetadata->getAttributes();
356270
$context = [];
357-
358271
if (isset($attributes['normalization_context']['groups'])) {
359272
$context['serializer_groups'] = $attributes['normalization_context']['groups'];
360273
}
361274

362275
if (isset($attributes['denormalization_context']['groups'])) {
363-
$context['serializer_groups'] = isset($context['serializer_groups']) ? array_merge($context['serializer_groups'], $attributes['denormalization_context']['groups']) : $attributes['denormalization_context']['groups'];
276+
if (isset($context['serializer_groups'])) {
277+
$context['serializer_groups'] += $attributes['denormalization_context']['groups'];
278+
} else {
279+
$context['serializer_groups'] = $attributes['denormalization_context']['groups'];
280+
}
364281
}
365282

366283
foreach ($this->propertyNameCollectionFactory->create($resourceClass, $context) as $propertyName) {
@@ -389,17 +306,15 @@ private function getPropertySchema(PropertyMetadata $propertyMetadata) : \ArrayO
389306
{
390307
$propertySchema = new \ArrayObject();
391308

392-
if ($description = $propertyMetadata->getDescription()) {
309+
if (null !== $description = $propertyMetadata->getDescription()) {
393310
$propertySchema['description'] = $description;
394311
}
395312

396-
$type = $propertyMetadata->getType();
397-
if (!$type) {
313+
if (null == $type = $propertyMetadata->getType()) {
398314
return $propertySchema;
399315
}
400316

401317
$valueSchema = new \ArrayObject();
402-
403318
$valueType = $type->isCollection() ? $type->getCollectionValueType() : $type;
404319

405320
switch ($valueType ? $valueType->getBuiltinType() : null) {

0 commit comments

Comments
 (0)