README

#安装 ##通过Composer

编辑 composer.json 并添加依赖

"ralphowino/swagger" : "dev-master"

##添加服务提供者

编辑 config/app.php 并在 providers 数组中添加 "Ralphowino/Swagger/SwaggerServiceProvider"

#入门指南

##初始化文档 要为您的api创建新的文档，请运行

php artisan swagger:init

##从命令行生成文档

有4种文档类型：api、资源、模型、操作

###Api

此文档类型允许您创建标准的swagger资源文档类型。

要生成一个，请使用以下命令

php artisan swagger:generate api apiname

###Resource

此文档类型是标准swagger资源的总结版本，包括两个变量：模型和操作。

要生成一个，请使用以下命令

php artisan swagger:generate resource resourcename

您将需要指定要包含的操作列表

###Operation

此文档类型代表您api中的一个单独的动作/路由。要生成一个，请使用以下命令

php artisan swagger:generate operation operationName

您将需要指定关于动作的不同细节，例如动词、路由等

###Model

此文档类型代表在您的api中使用的模型/自定义数据类型。要生成一个，请使用以下命令

php artisan swagger:generate model Modelname

您将需要指定模型的属性以及必需的属性

##快速教程

我们可以为具有简单CRUD功能的待办事项api创建一个快速的文档。

###初始化

php artisan swagger:init

确保您已将api域名更新到config/app.php中

###创建模型

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"

###创建操作

1. 创建待办事项

php artisan swagger:generate operation createTodo

一般详情

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

参数：body

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

2. 获取待办事项

php artisan swagger:generate operation getTodo

一般详情

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

参数：id

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

参数：if-match-none

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

参数：fields

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

3. 获取所有待办事项

php artisan swagger:generate operation getTodos

要填充操作，请输入以下答案

一般详情

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

参数：if-match-none

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

参数：id

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

参数：fields

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

参数：page

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

参数：per_page

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

4. 更新待办事项

php artisan swagger:generate operation updateTodo

一般详情

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

参数：body

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

5. 删除待办事项

php artisan swagger:generate operation deleteTodo

一般详情

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

###创建资源

php artisan swagger:generate resource todos

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

#即将推出功能

• JSON文档内的规范
• 模板
• 从代码生成
• 导入Postman文档
• 单元测试