Skip to content

Add mandatory id and annotations #1080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 12, 2020
Merged

Add mandatory id and annotations #1080

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
63cb3a0
Add mandatory id and annotations
dhernandez Mar 28, 2020
d094c19
Update dto.md
dhernandez Apr 5, 2020
fabb572
Update dto.md
dhernandez Apr 5, 2020
a74ec67
Apply suggestions from code review
alanpoulain Apr 12, 2020
23cd9e3
Fix indentation
alanpoulain Apr 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions core/dto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ use App\Dto\BookOutput;
*/
final class Book
{
public $id;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example is needs also a @ApiProperty(identifier=true)
And to be honest, I should also have a property called $code
So the InputDataTransformer actually transform the isbn into a code.
And then in the OutputDataTransformer, from this code into the name.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example only needs the annotation @ApiProperty(identifier=true) if you use another name to the property, like $code. But the example works without the annotation with the $id property.
Although, IMHO, Book entity shouldn't need a mandatory id property, because you have a BookInput and a BookOutput DTOs and BookInput have an id (called isbn).
So, to make a simple full example, that works with this issue, I think that adding an id called $id to Book is the clearest way.
Maybe, we can add also a note explaining the option of using $code property, annotated as identifier, and transforming it to isbn.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yup it's a good idea, at least to clarify the process.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can check fabb572 🙂

}
```

Expand Down Expand Up @@ -63,6 +64,8 @@ Similarly, the `output` attribute is used during [the serialization process](ser

The `input` and `output` attributes are taken into account by all the documentation generators (GraphQL and OpenAPI, Hydra).

Note that `Book` entity needs an id property. The simplest way is adding a public property called `$id`, as in the example. However, as in any other entity, you can use a private property, with getter and setter functions, and/or named it as you wish, provided you annotate it with `@ApiProperty(identifier=true)`. For instance, you could have a property called `$code`. So the `InputDataTransformer` actually transforms the isbn into a code. And then in the `OutputDataTransformer`, from this code into the name.

To create a `Book`, we `POST` a data structure corresponding to the `BookInput` class and get back in the response a data structure corresponding to the `BookOutput` class:

![Diagram post input output](images/diagrams/api-platform-post-i-o.png)
Expand All @@ -78,7 +81,10 @@ We have the following `BookInput`:
namespace App\Dto;

final class BookInput {
public $isbn;
/**
* @var string
*/
public $isbn;
}
```

Expand Down Expand Up @@ -142,7 +148,10 @@ To manage the output, it's exactly the same process. For example, we have the fo
namespace App\Dto;

final class BookOutput {
public $name;
/**
* @var string
*/
public $name;
}
```

Expand Down