Create a gist now

Instantly share code, notes, and snippets.

@kaz29 /Article.php
Last active Feb 18, 2016

What would you like to do?
Swagger サンプル(example.sonはswagger-phpで生成したファイルです、swagger-uiに食わせるとAPIドキュメントがみられます。)
<?php
namespace App\Model\Entity;
use Cake\ORM\Entity;
/**
* Article Entity.
*
* @SWG\Definition(
* definition="Article",
* required={
* "id", "user_id", "title", "body", "created", "modified"
* },
* @SWG\Property(
* property="id",
* type="integer",
* description="アーティクルid"
* ),
* @SWG\Property(
* property="user_id",
* type="integer",
* description="ユーザid"
* ),
* @SWG\Property(
* property="title",
* type="string",
* description="タイトル",
* maxLength=255
* ),
* @SWG\Property(
* property="body",
* type="string",
* description="記事本文"
* ),
* @SWG\Property(
* property="created",
* type="datetime",
* description="作成日時"
* ),
* @SWG\Property(
* property="modified",
* type="datetime",
* description="更新日時"
* )
* )
*/
class Article extends Entity
{
}
<?php
namespace App\Controller\Api;
use Cake\Event\Event;
use Cake\ORM\TableRegistry;
class ArticleController extends ApiController
{
...
/**
* Index method
*
* @return void
* @SWG\Get(
* path="/articles",
* description="記事一覧",
* produces={"application/json"},
* @SWG\Parameter(
* description="検索文字列",
* in="path",
* name="q",
* required=false,
* type="string"
* ),
* @SWG\Response(
* response=200,
* description="取得成功",
* @SWG\Schema(
* @SWG\Property(
* property="status",
* type="boolean",
* description="処理結果",
* ),
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(ref="#/definitions/IndexArticle"),
* description="記事",
* ),
* @SWG\Property(
* property="pagination",
* ref="#/definitions/PageInfo",
* description="ページ情報",
* ),
* )
* ),
* @SWG\Response(
* response="401",
* description="Unauthorized"
* ),
* )
*
* @SWG\Definition(
* definition="IndexArticle",
* allOf={
* @SWG\Schema(ref="#/definitions/Article"),
* },
* @SWG\Property(
* property="user",
* description="ユーザ情報",
* ref="#/definitions/User"
* )
* )
*/
public function index()
{
}
}
{
"swagger": "2.0",
"info": {
"title": "Swagger\u30b5\u30f3\u30d7\u30eb",
"description": "Swagger\u30b5\u30f3\u30d7\u30ebAPI\u4ed5\u69d8",
"contact": {
"name": "foo@example.com"
},
"license": {
"name": "\u30e9\u30a4\u30bb\u30f3\u30b9\u8868\u8a18"
},
"version": "1.0.0"
},
"host": "api.example.com",
"basePath": "/api",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/articles": {
"get": {
"description": "\u8a18\u4e8b\u4e00\u89a7",
"produces": [
"application/json"
],
"parameters": [
{
"name": "q",
"in": "path",
"description": "\u691c\u7d22\u6587\u5b57\u5217",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "\u53d6\u5f97\u6210\u529f",
"schema": {
"properties": {
"status": {
"description": "\u51e6\u7406\u7d50\u679c",
"type": "boolean"
},
"data": {
"description": "\u8a18\u4e8b",
"type": "array",
"items": {
"$ref": "#/definitions/IndexArticle"
}
},
"pagination": {
"description": "\u30da\u30fc\u30b8\u60c5\u5831",
"$ref": "#/definitions/PageInfo"
}
}
}
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/users": {
"get": {
"description": "\u30e6\u30fc\u30b6\u4e00\u89a7",
"produces": [
"application/json"
],
"parameters": [
{
"name": "q",
"in": "path",
"description": "\u691c\u7d22\u6587\u5b57\u5217",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "\u53d6\u5f97\u6210\u529f",
"schema": {
"properties": {
"status": {
"description": "\u51e6\u7406\u7d50\u679c",
"type": "boolean"
},
"data": {
"description": "\u30e6\u30fc\u30b6\u60c5\u5831",
"type": "array",
"items": {
"$ref": "#/definitions/User"
}
},
"pagination": {
"description": "\u30da\u30fc\u30b8\u60c5\u5831",
"$ref": "#/definitions/PageInfo"
}
}
}
},
"401": {
"description": "Unauthorized"
}
}
}
}
},
"definitions": {
"PageInfo": {
"required": [
"page_count",
"current_page",
"has_next_page",
"has_prev_page",
"count",
"limit"
],
"properties": {
"page_count": {
"description": "\u7dcf\u30da\u30fc\u30b8\u6570",
"type": "integer",
"format": "int32"
},
"current_page": {
"description": "\u73fe\u5728\u306e\u30da\u30fc\u30b8\u756a\u53f7",
"type": "integer",
"format": "int32"
},
"has_next_page": {
"description": "\u6b21\u30da\u30fc\u30b8\u6709/\u7121",
"type": "boolean"
},
"has_prev_page": {
"description": "\u524d\u30da\u30fc\u30b8\u6709/\u7121",
"type": "boolean"
},
"count": {
"description": "\u30da\u30fc\u30b8\u5185\u30a2\u30a4\u30c6\u30e0\u6570",
"type": "integer",
"format": "int32"
},
"limit": {
"description": "\u30da\u30fc\u30b8\u5185\u6700\u5927\u30a2\u30a4\u30c6\u30e0\u6570",
"type": "integer",
"format": "int32"
}
}
},
"IndexArticle": {
"properties": {
"user": {
"description": "\u30e6\u30fc\u30b6\u60c5\u5831",
"$ref": "#/definitions/User"
}
},
"allOf": [
{
"$ref": "#/definitions/Article"
}
]
},
"Article": {
"required": [
"id",
"user_id",
"title",
"body",
"created",
"modified"
],
"properties": {
"id": {
"description": "\u30a2\u30fc\u30c6\u30a3\u30af\u30ebid",
"type": "integer"
},
"user_id": {
"description": "\u30e6\u30fc\u30b6id",
"type": "integer"
},
"title": {
"description": "\u30bf\u30a4\u30c8\u30eb",
"type": "string",
"maxLength": 255
},
"body": {
"description": "\u8a18\u4e8b\u672c\u6587",
"type": "string"
},
"created": {
"description": "\u4f5c\u6210\u65e5\u6642",
"type": "datetime"
},
"modified": {
"description": "\u66f4\u65b0\u65e5\u6642",
"type": "datetime"
}
}
},
"User": {
"required": [
"id",
"username",
"password",
"created",
"modified"
],
"properties": {
"id": {
"description": "\u30e6\u30fc\u30b6id",
"type": "integer"
},
"username": {
"description": "\u30e6\u30fc\u30b6\u540d",
"type": "string",
"maxLength": 255
},
"password": {
"description": "\u30d1\u30b9\u30ef\u30fc\u30c9",
"type": "string",
"maxLength": 255
},
"created": {
"description": "\u4f5c\u6210\u65e5\u6642",
"type": "datetime"
},
"modified": {
"description": "\u66f4\u65b0\u65e5\u6642",
"type": "datetime"
}
}
}
}
}
<?php
/**
* @SWG\Swagger(
* basePath="/api",
* host="api.example.com",
* schemes={"https"},
* produces={"application/json"},
* consumes={"application/json"},
* @SWG\Info(
* version="1.0.0",
* title="Swaggerサンプル",
* description="SwaggerサンプルAPI仕様",
* @SWG\Contact(name="foo@example.com"),
* @SWG\License(name="ライセンス表記")
* ),
*
* @SWG\Definition(
* definition="PageInfo",
* required={"page_count", "current_page", "has_next_page", "has_prev_page", "count", "limit"},
* @SWG\Property(
* property="page_count",
* type="integer",
* format="int32",
* description="総ページ数"
* ),
* @SWG\Property(
* property="current_page",
* type="integer",
* format="int32",
* description="現在のページ番号"
* ),
* @SWG\Property(
* property="has_next_page",
* type="boolean",
* description="次ページ有/無"
* ),
* @SWG\Property(
* property="has_prev_page",
* type="boolean",
* description="前ページ有/無"
* ),
* @SWG\Property(
* property="count",
* type="integer",
* format="int32",
* description="ページ内アイテム数"
* ),
* @SWG\Property(
* property="limit",
* type="integer",
* format="int32",
* description="ページ内最大アイテム数"
* )
* )
* )
*/
<?php
namespace App\Model\Entity;
use Cake\ORM\Entity;
/**
* User Entity.
*
* @SWG\Definition(
* definition="User",
* required={
* "id", "username", "password", "created", "modified"
* },
* @SWG\Property(
* property="id",
* type="integer",
* description="ユーザid"
* ),
* @SWG\Property(
* property="username",
* type="string",
* description="ユーザ名",
* maxLength=255,
* ),
* @SWG\Property(
* property="password",
* type="string",
* description="パスワード",
* maxLength=255,
* ),
* @SWG\Property(
* property="created",
* type="datetime",
* description="作成日時"
* ),
* @SWG\Property(
* property="modified",
* type="datetime",
* description="更新日時"
* )
* )
*/
class User extends Entity
{
}
<?php
namespace App\Controller\Api;
use Cake\Event\Event;
use Cake\ORM\TableRegistry;
class UsersController extends ApiController
{
...
/**
* Index method
*
* @return void
* @SWG\Get(
* path="/users",
* description="ユーザ一覧",
* produces={"application/json"},
* @SWG\Parameter(
* description="検索文字列",
* in="path",
* name="q",
* required=false,
* type="string"
* ),
* @SWG\Response(
* response=200,
* description="取得成功",
* @SWG\Schema(
* @SWG\Property(
* property="status",
* type="boolean",
* description="処理結果",
* ),
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(ref="#/definitions/User"),
* description="ユーザ情報",
* ),
* @SWG\Property(
* property="pagination",
* ref="#/definitions/PageInfo",
* description="ページ情報",
* ),
* )
* ),
* @SWG\Response(
* response="401",
* description="Unauthorized"
* ),
* )
*/
public function index()
{
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment