Schema references

[netdjw]

In my documentation what I created by hand I use definitions like this:

  /api/login:
    post:
      tags:
      - login
      summary: login into the API
      description: |
        You need to log in, receive a token, what you can use to the next steps
      parameters: 
      - in: body
        name: content
        schema:
          $ref: '#/definitions/credential'
      responses:
        200:
          description: you are logged in
          schema:
            $ref: '#/definitions/token'

Here are the definitions to this above example:

definitions:
  credential:
    type: object
    required:
    - email
    - password
    properties:
      email:
        type: string
        example: "[email protected]"
      password:
        type: string
        example: "secret"
        
  token:
    type: object
    properties:
      token:
        type: string
        example: "JWT string"

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.

[mtrajano]

This is a cool idea! Open to any suggestions on how you'd implement this

[netdjw]

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.

[netdjw]

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.