Use default value of PHP properties to Swagger doc

[aaa2000]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#2363
License	MIT
Doc PR

Add default and example information to swagger context if php properties
have default values so the exemple documentation section use these values.

With a class

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiProperty;
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Ramsey\Uuid\UuidInterface;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @ORM\Entity
 * @ApiResource(
 *     normalizationContext={"groups": {"person:read"}}
 * )
 * @ApiResource
 */
class Person
{
    /**
     * @var UuidInterface
     *
     * @ApiProperty(identifier=true)
     * @Groups({"person:read"})
     *
     * @ORM\Id
     * @ORM\Column(type="uuid", unique=true)
     * @ORM\GeneratedValue(strategy="CUSTOM")
     * @ORM\CustomIdGenerator(class="Ramsey\Uuid\Doctrine\UuidGenerator")
     */
    public $code;

    /**
     * @var bool
     *
     * @Groups({"person:read", "person:write"})
     *
     * @ORM\Column(type="boolean", options={"default" : false})
     */
    public $isActive = true;

    /**
     * @var integer
     *
     * @Groups({"person:read", "person:write"})
     *
     * @ORM\Column(type="integer", nullable=true)
     */
    public $int = 100;

    /**
     * @var array
     *
     * @Groups({"person:read", "person:write"})
     *
     * @ORM\Column(type="json_array", nullable=true)
     */
    public $array = ['aa', 'bb'];

    /**
     * @var string
     *
     * @ApiProperty(
     *     attributes={
     *         "swagger_context"={
     *             "example"="example string"
     *         }
     *     }
     * )
     *
     * @Groups({"person:read", "person:write"})
     *
     * @ORM\Column(nullable=true)
     */
    public $string = 'aaaaaa';
}

The swagger documentation displays

[dunglas]

Nice improvement! I made some design comments but I like the idea!

[soullivaneuh]

@dunglas Won't 2.3 be a better branch target for this?

[dunglas]

@soullivaneuh no because it's a new feature.

[aaa2000]

@dunglas PR updated to introduce the default and example properties in ApiProperty

[aaa2000]

decoration-priority="30" is correct ?

[dunglas]

LGTM

[aaa2000]

@meyerbaptiste done

[soyuka]

Should we also use the Doctrine default value in https://github.com/api-platform/core/blob/master/src/Bridge/Doctrine/Orm/Metadata/Property/DoctrineOrmPropertyMetadataFactory.php?

[aaa2000]

I also added the Doctrine default value but I'm not sure it's a good idea because with postgres, Doctrine insert a null value for the column, and there is the error
ERROR: null value in column "string" violates not-null constraint

I can use Doctrine default value as example value but a doctrine annotation @ORM\Column(name="created_at", type="datetime", options={"default": "CURRENT_TIMESTAMP"}) will display CURRENT_TIMESTAMP as example. Finally, I do not think that this is desirable to use the Doctrine default value

[soyuka]

I also added the Doctrine default value but I'm not sure it's a good idea because with postgres, Doctrine insert a null value for the column, and there is the error
ERROR: null value in column "string" violates not-null constraint

Not sure I got that, what is behind this insert?

About the second point, thoughts @api-platform/core-team ?

[aaa2000]

Given an entity with Doctrine default value

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiProperty;
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Ramsey\Uuid\UuidInterface;

/**
 * @ORM\Entity
 * @ApiResource
 */
class Bug
{
    /**
     * @var UuidInterface
     *
     * @ApiProperty(identifier=true)
     *
     * @ORM\Id
     * @ORM\Column(type="uuid", unique=true)
     * @ORM\GeneratedValue(strategy="CUSTOM")
     * @ORM\CustomIdGenerator(class="Ramsey\Uuid\Doctrine\UuidGenerator")
     */
    public $code;


    /**
     * @var string
     *
     * @ORM\Column(options={"default": "example name"})
     */
    public $name;
}

When I send the request curl -X POST "http://localhost:8080/bugs" -H "accept: application/ld+json" -H "Content-Type: application/ld+json" -d "{}"
Then I have the error

{
  "@context": "/contexts/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "An exception occurred while executing 'INSERT INTO bugs (code, name) VALUES (?, ?)' with params [\"4387fe5d-ce66-4783-a310-33256cd9c294\", null]:\n\nSQLSTATE[23502]: Not null violation: 7 ERROR:  null value in column \"name\" violates not-null constraint\nDETAIL:  Failing row contains (4387fe5d-ce66-4783-a310-33256cd9c294, null).",

To have the default value inserted with postgres, the query should be INSERT INTO bugs (code, name) VALUES ('4387fe5d-ce66-4783-a310-33256cd9c294', default );

So, it is maybe better to use the Doctrine default value as example instead of default property metadata and change https://github.com/api-platform/core/pull/2386/files#diff-fbaaae4f33f38c0ec0e318994cb386faR82 $propertyMetadata = $propertyMetadata->withDefault($fieldMapping['options']['default']); by $propertyMetadata = $propertyMetadata->withExample($fieldMapping['options']['default']);

[soyuka]

👍 if you can fix this and add a test case for it

[flug]

@aaa2000 you can fix et add test please for merge this pull request ?

[aaa2000]

I can't fix, the fix should be done in doctrine. The doctrine ORM doesn't take into account the options={"default": "example name"} when it create the insertion. The options seems to be used only for creating the database schema

[soyuka]

Okay nice, we'll open an issue to track this. I the meantime I'm 👍 to merge this.

[soyuka]

Thanks for the work @aaa2000

[teohhanhui]

I can't fix, the fix should be done in doctrine. The doctrine ORM doesn't take into account the options={"default": "example name"} when it create the insertion. The options seems to be used only for creating the database schema

It's not a bug. That's exactly what it's intended for, the default value at the database level. It'd be a bug if Doctrine ORM actually tries to use it. 😉