ralphowino/swagger

Installation

Via Composer

Edit composer.json and to require, _(*1)

"ralphowino/swagger" : "dev-master"

Add providers

Edit config/app.php and "Ralphowino/Swagger/SwaggerServiceProvider" in providers array, _(*2)

Getting Started

Initialize your docs

To create a new documentation for your api, run:, _(*3)

php artisan swagger:init

Generate Docs from CLI

There are 4 doc types: api, resource, model, operation, _(*4)

Api

This doc type allows you to create a standard swagger resource doc type., _(*5)

To generate one, use command:, _(*6)

php artisan swagger:generate api apiname

Resource

This doc type is a summarised version of the standard swagger resource and includes 2 variables: models and operations., _(*7)

To generate one, use command:, _(*8)

php artisan swagger:generate resource resourcename

You will be requested to specify a list of operations to include, _(*9)

Operation

This doc type represents a single action/route in your api. To generate one, use command:, _(*10)

php artisan swagger:generate operation operationName

You will be requested to specify different details about the action such as Verb, Route, etc, _(*11)

Model

This doc type represents a model/custom datatype used in your api. To generate one use command:, _(*12)

php artisan swagger:generate model Modelname

You will be asked properties of the model and the required ones, _(*13)

Quick Tutorial

We can create a quick documentation for a to-do list api with simple Crud function for todo items., _(*14)

Initialize

php artisan swagger:init

Make sure you have updated your api domain name in config/app.php, _(*15)

Create Models

php artisan swagger:generate model Todo --properties="id:integer, title:string, notes:text, completed:boolean, created_at:datetime, updated_at:datetime, completed_at:datetime, deleted_at:datetime" --required="id,title"


php artisan swagger:generate model Item --properties="title:string, notes:text, completed:boolean" --required="title"

Create Operations

1. Create Todo, _(*16)

php artisan swagger:generate operation createTodo

General details, _(*17)

verb: POST
path: todos
model: Todo
summary: Create a new todo item
notes:

Parameter: body, _(*18)

parameter: body
parameter.description: create a new todo item
parameter.location: body
parameter.type: iTodo
parameter.required: y
parameter.multiple: n

2.Get Todo, _(*19)

php artisan swagger:generate operation getTodo

General details, _(*20)

verb: GET
path: todos/{id}
model: Todo
summary: Get todo item using its id
notes: Get a todo item using its id. Define fields to retrieve or none if not changed

Parameter: id, _(*21)

parameter: id
parameter.description: id of todo item to retrieve
parameter.location: path
parameter.type: integer
parameter.required: y
parameter.multiple: n

Parameter: if-match-none, _(*22)

parameter: if-match-none
parameter.description: return if etag doesn't match
parameter.location: header
parameter.type: string
parameter.required: n
parameter.multiple: n

Parameter: fields, _(*23)

parameter: fields
parameter.description: fields to return (limited to fields available)
parameter.location: query
parameter.type: string
parameter.required: n
parameter.multiple: n

3.Get Todos, _(*24)

php artisan swagger:generate operation getTodos

To populate the operation enter the following answers:, _(*25)

General details, _(*26)

verb: GET
path: todo
model: array
type: Todo
summary: Get todo items
notes: Get a todo items paginated and filtered based on parameters

Parameter: if-match-none, _(*27)

parameter: if-match-none
parameter.description: return if etag doesn't match
parameter.location: header
parameter.type: string
parameter.required: n
parameter.multiple: n

Parameter: id, _(*28)

parameter: id
parameter.description: filter by ids. Comma separated list allowed
parameter.location: query
parameter.type: string
parameter.required: n
parameter.multiple: n

Parameter: fields, _(*29)

parameter: fields
parameter.description: fields to return (limited to fields available)
parameter.location: query
parameter.type: string
parameter.required: n
parameter.multiple: n

Parameter: page, _(*30)

parameter: page
parameter.description: page to display
parameter.location: query
parameter.type: integer
parameter.required: n
parameter.multiple: n

Parameter: per_page, _(*31)

parameter: per_page
parameter.description: items to display per page
parameter.location: query
parameter.type: integer
parameter.required: n
parameter.multiple: n

4.Update Todos, _(*32)

php artisan swagger:generate operation updateTodo

General details, _(*33)

verb: PUT
path: todos/{id}
model: Todo
summary: Update a todo item based on ID
notes:

Parameter: body, _(*34)

parameter: body
parameter.description: updated fields
parameter.location: body
parameter.type: iTodo
parameter.required: y
parameter.multiple: n

5.Delete Todo, _(*35)

php artisan swagger:generate operation deleteTodo

General details, _(*36)

verb: DELETE
path: todos/{id}
model: 
summary: Delete a todo item based on ID
notes:

Create Resource

php artisan swagger:generate resource todos

operation: gettodos
operation: gettodo
operation: createtodo
operation: updatetodo
operation: deletetodo

Upcoming features

• Specs within a json doc
• Templates
• Generate from code
• Import Postman doc
• Unit tests