Add a way to document model attributes with description, examples, etc.

[sNok3]

As the title suggests, when generating the docs for a controller which has model binding, the schema for the model will result in just the fields that the model has, without the annotations it has.

[romalytvynenko]

@sNok3 please share the example of your code and resulting docs. Also would be great to understand what your expected

[sNok3]

class Driver extends Model
{
    use HasFactory;
    use HasStatuses;

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        /**
         * The internal ID of the associated route
         *
         * @var int
         *
         * @example 1
         */
        'route_id',
        /**
         * The identifier of the activity
         *
         * @example 3d4b6f0e-2b0b-4b0b-8b4b-0b2b4b0b2b4b
         */
        'identifier'
   ];

So as you can see, I have annotations for both fields here, but under the schemas, there are is no information about the model.

[romalytvynenko]

@sNok3 ooh, gotcha. So basically you want to annotate the model fields with descriptions and examples?

Currently this is not supported.

You can use API resources and there you can add the descriptions.

However, I'll keep this issue open to add this possibility in future.

[sNok3]

Yeah, that is exactly what I needed. However, using API resources in the controller method isn't really my way to go for now since I have a big codebase.

However, I'll gladly wait for this to get implemented!

[alecpl]

At least type and description could be fetched from the @property definitions on the model class, please.

[romalytvynenko]

@chrisvanlier2005 as far as I remember, you've tried implementing @property support on model classes in your Scramble fork?

[chrisvanlier2005]

@romalytvynenko That's correct. I've implemented a PropertyTypesFromPhpdocExtension (private repo) that retrieves PHPDoc types from @property, @property-read, and @var tags on properties, as well as promoted @param tags.
However, this extension only handles type fetching... descriptions and other annotations aren't currently supported. In my opinion, those should be reserved for the API Resource layer instead

If there is interest, i'd be willing to submit a PR 🙂

[romalytvynenko]

@chrisvanlier2005 please go ahead, I'll be glad to add descriptions support on top of your extension if needed

[chrisvanlier2005]

Awesome, i'll submit PR when I have time 🙂