Skip to content

Commit ddee00d

Browse files
yiviyivi
authored
Update "Changing Operations [...]" section (#1284)
1 parent 9773011 commit ddee00d

File tree

2 files changed

+69
-36
lines changed

2 files changed

+69
-36
lines changed

‎core/openapi.md

Lines changed: 69 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -189,9 +189,8 @@ resources:
189189
```xml
190190
<?xml version="1.0" encoding="UTF-8" ?>
191191
<resources xmlns="https://api-platform.com/schema/metadata"
192-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
193-
xsi:schemaLocation="https://api-platform.com/schema/metadata
194-
https://api-platform.com/schema/metadata/metadata-2.0.xsd">
192+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
193+
xsi:schemaLocation="https://api-platform.com/schema/metadata https://api-platform.com/schema/metadata/metadata-2.0.xsd">
195194
<resource class="App\Entity\Product">
196195
<property name="name">
197196
<attribute name="openapi_context">
@@ -311,58 +310,96 @@ You also have full control over both built-in and custom operations documentatio
311310

312311
[codeSelector]
313312

313+
```php
314+
<?php
315+
// api/src/Entity/Rabbit.php
316+
317+
use ApiPlatform\Core\Annotation\ApiProperty;
318+
use ApiPlatform\Core\Annotation\ApiResource;
319+
use App\Controller\RandomRabbit;
320+
321+
#[ApiResource(collectionOperations: [
322+
'create_rabbit' => [
323+
'method' => 'post',
324+
'path' => '/rabbit/create',
325+
'controller' => RandomRabbit::class,
326+
'openapi_context' => [
327+
'summary' => 'Create a rabbit picture',
328+
'description' => "# Pop a great rabbit picture by color!\n\n![A great rabbit](https://rabbit.org/graphics/fun/netbunnies/jellybean1-brennan1.jpg)",
329+
'requestBody' => [
330+
'content' => [
331+
'application/json' => [
332+
'schema' => [
333+
'type' => 'object',
334+
'properties' =>
335+
[
336+
'name' => ['type' => 'string'],
337+
'description' => ['type' => 'string'],
338+
],
339+
],
340+
'example' => [
341+
'name' => 'Mr. Rabbit',
342+
'description' => 'Pink Rabbit',
343+
],
344+
],
345+
],
346+
],
347+
],
348+
],
349+
]
350+
)]
351+
class Rabbit
352+
{}
353+
```
354+
314355
```yaml
315356
resources:
316357
App\Entity\Rabbit:
317358
collectionOperations:
318-
create_user:
319-
method: get
320-
path: '/rabbit/rand'
359+
create_rabbit:
360+
method: post
361+
path: '/rabbit/create'
321362
controller: App\Controller\RandomRabbit
322-
# if you are using OpenApi V2 (Swagger) use 'swagger_context' instead of 'openapi_context'
323363
openapi_context:
324364
summary: Random rabbit picture
325365
description: >
326366
# Pop a great rabbit picture by color!
327367
328368
![A great rabbit](https://rabbit.org/graphics/fun/netbunnies/jellybean1-brennan1.jpg)
329369
330-
parameters:
331-
-
332-
in: body
333-
schema:
334-
type: object
335-
properties:
336-
name: {type: string}
337-
description: {type: string}
338-
example:
339-
name: Rabbit
340-
description: Pink rabbit
370+
requestBody:
371+
content:
372+
application/json:
373+
schema:
374+
type: object
375+
properties:
376+
name: { type: string }
377+
description: { type: string }
378+
example:
379+
name: Mr. Rabbit
380+
description: Pink rabbit
381+
341382
```
342383

343384
```xml
344385
<?xml version="1.0" encoding="UTF-8" ?>
345386
<resources xmlns="https://api-platform.com/schema/metadata"
346-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
347-
xsi:schemaLocation="https://api-platform.com/schema/metadata
387+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
388+
xsi:schemaLocation="https://api-platform.com/schema/metadata
348389
https://api-platform.com/schema/metadata/metadata-2.0.xsd">
349390
<resource class="App\Entity\Rabbit">
350391
<collectionOperations>
351-
<collectionOperation name="create_user">
352-
<attribute name="method">get</attribute>
353-
<attribute name="path">/rabbit/rand</attribute>
392+
<collectionOperation name="create_rabbit">
393+
<attribute name="path">/rabbit/create</attribute>
394+
<attribute name="method">post</attribute>
354395
<attribute name="controller">App\Controller\RandomRabbit</attribute>
355-
<!-- if you are using OpenApi V2 (Swagger) use 'swagger_context' instead of 'openapi_context' -->
356396
<attribute name="openapi_context">
357-
<attribute name="summary">Random rabbit picture</attribute>
358-
<attribute name="description">
359-
# Pop a great rabbit picture by color!
397+
<attribute name="summary">Create a rabbit picture </attribute>
398+
<attribute name="description"># Pop a great rabbit picture by color!!
360399

361-
![A great rabbit](https://rabbit.org/graphics/fun/netbunnies/jellybean1-brennan1.jpg)
362-
</attribute>
363-
<attribute name="parameters">
364-
<attribute>
365-
<attribute name="in">body</attribute>
400+
![A great rabbit](https://rabbit.org/graphics/fun/netbunnies/jellybean1-brennan1.jpg)</attribute>
401+
<attribute name="content">
402+
<attribute name="application/json">
366403
<attribute name="schema">
367404
<attribute name="type">object</attribute>
368405
<attribute name="properties">
@@ -374,10 +411,6 @@ resources:
374411
</attribute>
375412
</attribute>
376413
</attribute>
377-
<attribute name="example">
378-
<attribute name="name">Rabbit</attribute>
379-
<attribute name="description">Pink rabbit</attribute>
380-
</attribute>
381414
</attribute>
382415
</attribute>
383416
</attribute>

‎distribution/images/swagger-ui-2.png

54.1 KB
Loading

0 commit comments

Comments
 (0)