Open netdjw opened 5 years ago
This is a cool idea! Open to any suggestions on how you'd implement this
Maybe start the parsing on models... definitions based on models. But some definitions doesn't have models, but if I need to create some unused models, it's acceptable deal for me to create a full & nice documentation.
For example something like this:
/**
* name {string} Title of post
* lead {string} Short description of content
* content {string} Content of post
* tags {string} Coma-spearated string of tags
* is_active {boolean} Post is active
* lang_id {number} ID of a `Lang` model
* lang {Lang} The attached `Lang` model
*/
class Blog extends Model
{
use SoftDeletes;
protected $table = 'blog';
protected $fillable = [
'name',
'lead',
'content',
'tags',
'is_active',
'lang_id',
];
protected $hidden = ['updated_at', 'deleted_at'];
public function lang() {
return $this->hasOne('App\Lang');
}
}
This format is based on docBlock, and give information about field types too.
number
, string
, boolean
are basic types, and in this example the Lang
is an other model definition.
In this case the swagger definition is based on docBlock and if I miss something to document there it will not show in the final documentation.
In my documentation what I created by hand I use
definitions
like this:Here are the definitions to this above example:
It would be nice if the laravel-swagger could be generate this definitions because it's a very useful part of the API documentation when the frontend developers thinking about their models.