swagger-php
A php swagger annotation and parsing library
Welcome to Swagger-PHP’s documentation! — Swagger-PHP documentation
I am using Swagger-php and Swagger-UI and it all works just fine but for one annoyance. The UI that Swagger-UI creates has the expected click-to-expand sections for my API routes, but the title of each one appears to be the JSON file generated and not any name I can give it. After the title, the description is the one I give in my annotation, but the title I seem to have no control over.
So if I have routes that begin with a resourcePath of /foo, and a description that says "Foo API Functions," the UI looks like:
foo.json : Foo API Functions
I don't want "foo.json" I'd much rather specify what this says. Like just "Foo" or even "Foo Functions" and then change my description to something more meaningful like, "This is where you find the foo functions."
Am I missing which annotation to use for this?
Source: (StackOverflow)
I am new to this stuff but I love it. I made a little REST Api using the Slim Framework. Now I would like to have an ongoing documentation about it. I think swagger is the right choice but I have not found out yet how to integrate it ?
Cheers & thanks for your patience :)
Source: (StackOverflow)
in my Zend-Application I am writing a little API for mobile-Applications.
To make it easy for the mobile-developers I am using Swagger.
Up to now everything works fine except one GET-Request.
When I am calling /user/messages/{sessionToken}?numMessages={numMessages}&pageNr={pageNr} in a browser I get the results I want, but when I try to let Swagger do this request, only the sessionToken is transmitted. I tried this annotations for Swagger:
/**
* @SWG\Api(path="/user/messages/{sessionToken}?numMessages={numMessages}&pageNr={pageNr}",
* @SWG\Operation(
* method="GET",
* summary="Gets messages paged",
* notes="",
* type="string",
* nickname="getUsermessagesPaged",
* authorizations={},
* @SWG\Parameter(
* name="sessionToken",
* description="The token from an active user session",
* required=true,
* type="string",
* paramType="path",
* allowMultiple=true
* ),
* @SWG\Parameter(
* name="numMessages",
* description="number of messages on page (numMessages & pageNr are ignored if not both are set)",
* required=true,
* type="string",
* paramType="query",
* allowMultiple=true
* ),
* @SWG\Parameter(
* name="pageNr",
* description="pagenumber (numMessages & pageNr are ignored if not both are set)",
* required=true,
* type="string",
* paramType="query",
* allowMultiple=true
* ),
* @SWG\ResponseMessage(code=200, message="json {messages => 'user_messages'}"),
* @SWG\ResponseMessage(code=400, message="json with error 'not logged in'")
* )
* )
*/
Does anybody see my mistake?
Any help is welcome.
Kind regards
rholtermann
Update: As suggested I changed both paramTypes to "query" and changed the path:
@SWG\Api(path="/user/messages/{sessionToken}",
but it didn't work eighter.
xdebug in eclipse PDT shows:
requestURI => /ias/public/user/messages/{sessionToken}
and
- queryParams => Zend\\Stdlib\\Parameters
- *ArrayObject*storage => Array[0]
- => <Uninitialized>
the swagger JSON is:
{
"apiVersion": "1.0.0",
"swaggerVersion": "1.2",
"apis": [
{
"path": "\/user",
"description": "Operations about users"
}
],
"info": {
"title": "Mobile access api",
"description": "This is the xxx mobile access api.",
"termsOfServiceUrl": null,
"contact": "xxx",
"license": null,
"licenseUrl": null,
"_partialId": null,
"_partials": [ ],
"_context": {
"comment": "\/**\ * @SWG\\Info(\ * title="Mobile access api",\ * description="This is the xxx mobile access api.",\ * contact="xxx",\ * )\ *\/",
"line": 3
}
}
}
Here is th output of /user:
{
"basePath": "http://localhost/ias/public",
"swaggerVersion": "1.2",
"apiVersion": "1.0.0",
"resourcePath": "/user",
"apis": [
{
"path": "/user/balance/{sessionToken}",
"operations": [
{
"method": "GET",
"summary": "Gets userbalance",
"nickname": "getUserdata",
"type": "string",
"parameters": [
{
"paramType": "path",
"name": "sessionToken",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The token from an active user session"
}
],
"responseMessages": [
{
"code": 200,
"message": "json {balance => 'user_balance'}"
},
{
"code": 400,
"message": "json with error 'not logged in'"
}
],
"notes": "",
"authorizations": {}
}
]
},
{
"path": "/user/login",
"operations": [
{
"method": "POST",
"summary": "Logs user into the system",
"nickname": "loginUser",
"type": "string",
"parameters": [
{
"paramType": "form",
"name": "email",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The user email for login"
},
{
"paramType": "form",
"name": "password",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The password for login in clear text"
}
],
"responseMessages": [
{
"code": 200,
"message": "json with session_id, user_id, user_balance"
},
{
"code": 400,
"message": "json with error 'no user with given email and password'"
},
{
"code": 400,
"message": "json with error 'invalid input'"
},
{
"code": 400,
"message": "json with error 'no post request'"
}
],
"notes": "",
"authorizations": {}
}
]
},
{
"path": "/user/logout",
"operations": [
{
"method": "POST",
"summary": "Logs user out",
"nickname": "logoutUser",
"type": "string",
"parameters": [
{
"paramType": "form",
"name": "sessionToken",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The token from an active user session"
}
],
"responseMessages": [
{
"code": 200,
"message": "json {result => 'deleted'}"
},
{
"code": 400,
"message": "json with error 'no user_session with given sid'"
},
{
"code": 400,
"message": "json with error 'invalid input'"
},
{
"code": 400,
"message": "json with error 'no post request'"
}
],
"notes": "",
"authorizations": {}
}
]
},
{
"path": "/user/messages/{sessionToken}",
"operations": [
{
"method": "GET",
"summary": "Gets new messages",
"nickname": "getUsermessages",
"type": "string",
"parameters": [
{
"paramType": "path",
"name": "sessionToken",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The token from an active user session"
}
],
"responseMessages": [
{
"code": 200,
"message": "json {messages => 'user_messages'}"
},
{
"code": 400,
"message": "json with error 'not logged in'"
}
],
"notes": "",
"authorizations": {}
},
{
"method": "GET",
"summary": "Gets messages paged",
"nickname": "getUsermessagesPaged",
"type": "string",
"parameters": [
{
"paramType": "path",
"name": "sessionToken",
"type": "string",
"required": true,
"description": "The token from an active user session"
},
{
"paramType": "query",
"name": "numMessages",
"type": "string",
"required": true,
"description": "number of messages on page (numMessages & pageNr are ignored if not both are set)"
},
{
"paramType": "query",
"name": "pageNr",
"type": "string",
"required": true,
"description": "pagenumber (numMessages & pageNr are ignored if not both are set)"
}
],
"responseMessages": [
{
"code": 200,
"message": "json {messages => 'user_messages'}"
},
{
"code": 400,
"message": "json with error 'not logged in'"
}
],
"notes": "",
"authorizations": {}
}
]
},
{
"path": "/user/userdata",
"operations": [
{
"method": "POST",
"summary": "Posts userdata",
"nickname": "postUserdata",
"type": "string",
"parameters": [
{
"paramType": "form",
"name": "sessionToken",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The token from an active user session"
},
{
"paramType": "form",
"name": "password",
"type": "string",
"required": false,
"allowMultiple": false,
"description": "new password"
},
{
"paramType": "form",
"name": "address",
"type": "string",
"required": false,
"allowMultiple": false,
"description": "new address"
},
{
"paramType": "form",
"name": "housenr",
"type": "string",
"required": false,
"allowMultiple": false,
"description": "new housenr"
},
{
"paramType": "form",
"name": "zip",
"type": "string",
"required": false,
"allowMultiple": false,
"description": "new zip"
},
{
"paramType": "form",
"name": "city",
"type": "string",
"required": false,
"allowMultiple": false,
"description": "new city"
},
{
"paramType": "form",
"name": "email",
"type": "string",
"required": false,
"allowMultiple": false,
"description": "new email"
}
],
"responseMessages": [
{
"code": 200,
"message": "json {user => 'userdata'}"
},
{
"code": 400,
"message": "json with error 'not logged in'"
}
],
"notes": "",
"authorizations": {}
}
]
},
{
"path": "/user/userdata/{sessionToken}",
"operations": [
{
"method": "GET",
"summary": "Gets userdata",
"nickname": "getUserdata",
"type": "string",
"parameters": [
{
"paramType": "path",
"name": "sessionToken",
"type": "string",
"required": true,
"allowMultiple": false,
"description": "The token from an active user session"
}
],
"responseMessages": [
{
"code": 200,
"message": "json {user => 'userdata', user_limit => 'userLimits'}"
},
{
"code": 400,
"message": "json with error 'not logged in'"
}
],
"notes": "",
"authorizations": {}
}
]
}
],
"produces": [
"application/json"
]
}
The error seems to be, that my swagger-ui doesn't send out any query-params?
Here is an example with only one query-param, the sessionToken:
(monitored by FireBug 2.0.6)
GET /ias/public/user/balance HTTP/1.1
Host: localhost
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: application/json
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/json
Referer: http://localhost/ias/swagger/
Cookie: __utma=111872281.581414660.1366700677.1394721873.1394723866.255; uvts=sB5Dda3cZBNdaTk; searchpanel-close=set
Connection: keep-alive
The answer was:
HTTP/1.1 400 Bad Request
Date: Tue, 25 Nov 2014 14:58:20 GMT
Server: Apache/2.4.9 (Win32) PHP/5.5.12
X-Powered-By: PHP/5.5.12
Content-Length: 25
Connection: close
Content-Type: application/json; charset=utf-8
The answer was correct, because no sessionToken was transmitted.
This requests works, but it doesn't come from swagger-ui:
GET /ias/public/user/balance?sessionToken=54275cc6358e42c4b1fb1d8daf850b52 HTTP/1.1
Host: localhost
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Cookie: __utma=111872281.581414660.1366700677.1394721873.1394723866.255; uvts=sB5Dda3cZBNdaTk; searchpanel-close=set
Connection: keep-alive
Source: (StackOverflow)
I'm trying to pass an object and a string to the function and test it in restler,
but I'm getting this error:
"error": {
"code": 400,
"message": "Bad Request: `user` is required but missing."
},
in the documentation I wrote:
/**
*
* @param User $user user object
*
* @param string $lang the language of the name e.g. "en" or "ar".
*
* @url POST /login/
*/
and this is the function:
public static function login(User $user,$lang) {
....
}
I'm using the pre-last version of restler.
Source: (StackOverflow)
I want to start to use swagger rest api on my mac, but I am not really familiar with swagger and how to start to work on it. I searched to find a good tutorial but unfortunately I couldn't find any useful and step by step tutorial! Can some one please give me a good explanation of how to start?
Thanks
Source: (StackOverflow)
I am creating a Restful api in php using Slim framework. To document the api's am using Swagger-php Annotations. How to annotate the Request Headers for a api ?
Source: (StackOverflow)
I have an app which uses a Swagger API. It's built on top of a mySQL database backend.
I wanted to use either the Swagger layer, or if this is not possible - the mySQL layer to produce a compliant OData feed:
http://en.wikipedia.org/wiki/Open_Data_Protocol
The mechanism of conversation should ideally use PHP, but any language will do.
Is there any well-maintained libraries that assist in exposing data to OData consuming services from either Swagger or from mySQL?
Source: (StackOverflow)
I'm trying to use Swagger-PHP with my CakePHP project and I'm having some issues. Has anyone set this up? Do you have any advice? I've successfully installed swagger-php via composer and it's loaded within my Controller (see below). I'm trying to render a spec via a web view and I'm not quite sure why registry isn't being populated or if even needs to be.
The following is inside of ApiController.php
use Swagger\Annotations as SWG;
use Swagger\Swagger;
public function swagger(){
$path = APP . 'Model'; //Path to the app directory
$swagger = Swagger::discover($path,APP . 'Model/Behavior');
debug($swagger);
//$swagger->jsonEncode($swagger->registry['/api']);
$swagResults = $swagger->registry;
debug($swagResults);
$this->set(array(
'results' => $swagResults,
'_serialize' => 'results'
));
}
Results
object(Swagger\Swagger) {
resourceList => array()
registry => array()
models => array()
[protected] fileList => array(
(int) 0 => '~/Sites/com/sitename-api/app/Model/[ModelName].php',
... All of my models
)
[protected] path => '~/Sites/com/sitename-api/app/Model'
[protected] excludePath => '~/Sites/com/sitename-api/app/Model/Behavior'
[protected] cache => object(Doctrine\Common\Cache\ArrayCache) {
[private] data => array(
'DoctrineNamespaceCacheKey[]' => (int) 1,
'[][1]' => 'a:4:{s:8:"registry";a:0:{}s:6:"models";a:0:{}s:4:"path";N;s:11:"excludePath";N;}',
'[cd9db43f54f6017ba1a20037c1577eb4d2017868][1]' => 'a:4:{s:8:"registry";a:0:{}s:6:"models";a:0:{}s:4:"path";s:56:"~/Sites/com/sitename-api/app/Model";s:11:"excludePath";s:65:"~/Sites/com/sitename-api/app/Model/Behavior";}'
)
}
[protected] cacheKey => 'cd9db43f54f6017ba1a20037c1577eb4d2017868'
}
So, basically $swagResults is empty and I'm guessing this shouldn't be, right?
Source: (StackOverflow)
I'm trying to use Swagger-ui for my json-rpc server which was written by php. I use Swagger-PHP to generate json complaint container for Swagger-ui. So, I'm very new to Swagger and I use annotation for methods like that:
/**
* @SWG\Resource(
* apiVersion="0.2",
* swaggerVersion="0.8",
* basePath="http://mydomain.com",
* @SWG\Api(
* path="/rpc/json/server.php",
* description="Operations about Devices",
* @SWG\Operations(
* @SWG\Operation(
* method="POST",
* summary="Get device by ID",
* nickname="getDevice",
* @SWG\Parameters(
* @SWG\Parameter(
* name="deviceID",
* description="device id",
* required="true",
* type="string"
* )
* ),
* @SWG\ResponseMessages(
* @SWG\ResponseMessage(code=404, message="Device not found")
* )
* )
* )
* )
* )
*/
In SWG\Operation I need to add one more "method" in correspondence with json-rpc spec.
As a result all requests will use POST method as part of http and json container will have its own "method" for each one.
The question - where should I start searching to solve this issue?
Sorry for my English. Not native.
Source: (StackOverflow)
I am trying to write a little Api using Slim. I want to have it documented very well so I installed swagger-php and UI and investigated on it the last days. For some reason my petstore demo is missing all the post annotations. My API will look like in this example:
http://coenraets.org/blog/2011/12/restful-services-with-jquery-php-and-the-slim-framework/
How would the swagger annotations for the addWine() function look like?
How do I annotate the result of the function (last insert id), since it is no model ?
An example would be really great.
Thank you
Source: (StackOverflow)
I have a REST webservice using Codeigniter and using this lib : https://github.com/chriskacerguis/codeigniter-restserver
I want to generate documentation for this web service. I look to use Swagger UI to generate this documentation. But, i didn't find any documentation how to use Swagger with Codeigniter.
The only project using this two technologies is this one, but don't have a good documentation : https://github.com/panxp/codeigniter-swagger
Can someone paste an example using this two technologies or give me a link to a good documentation ?
Of course, if there is another good lib to generate documentation, I'll take it if it's usable with Codeigniter.
Have a good day.
Source: (StackOverflow)
I am trying to work with swagger-codegen to generate code based on my Swagger resource file. However, I am running into the following error when attempting to generate code:
base path is http://my.documentation.com/api/docs/v1.json
java.io.FileNotFoundException: http://my.documentation.com/api/docs/v1.json/authenticateUser
It seems that swagger-codegen is attempting to read the method definition by appending the operation name after v1.json, but I am not sure why, as the operation name is defined inside v1.json itself:
{
"basePath":"https://my.api.com/v1",
"swaggerVersion":"1.2",
"apiVersion":"1.0.0",
"resourcePath":"v1",
"apis":[
{
"path":"/authenticateUser",
"description":"Authenticates a user into the API",
"operations":[
{
"method":"GET",
"summary":"Authenticates a user into the API",
"nickname":"authenticateUser",
"parameters":[
{
"paramType":"query",
"name":"username",
"type":"string",
"required":true,
"description":"Name of of user to authenticate"
},
{
"paramType":"query",
"name":"password",
"type":"string",
"required":true,
"description":"User's password"
}
],
"notes":"Returns access token in the response object"
}
]
},
...
]
}
I am not entirely sure what format swagger-codegen is expecting. Do the basePath for the API and the documentation for the API need to be the same? Note that the documentation for the documentation is hosted on a separate basePath than the API itself. I am not sure if this matters.
I will also note that my swagger resource file v1.json was generated with swagger-php and is working fine with swagger-ui.
Source: (StackOverflow)
Example swagger markup for a model
* @SWG\Model(
* id="UserSubscriptionSearchResultsFilter",
* @SWG\Property(name="total", type="integer"),
* @SWG\Property(name="perPage", type="integer"),
* @SWG\Property(name="query", type="string"),
* @SWG\Property(name="sortColumn", type="string"),
* @SWG\Property(name="sortDirection", type="string"),
* )
*/
/**
* @SWG\Model(
* id="UserSubscriptionSearchResults",
* @SWG\Property(name="results",type="array", items="$ref:UserSubscriptionRepository"),
* @SWG\Property(name="total", type="integer"),
* @SWG\Property(name="filter",type="object", uniqueItems="$ref:UserSubscriptionSearchResultsFilter")
* )
*/
Right now the schema looks like:
"filter": "object"
Instead what I want to see is:
"filter": {
"total": 0,
"perPage": 0,
"query": "",
"sortColumn": "",
"sortDirection": ""
}
Right now I've only been able to create an array object that looks relatively similar to this, but it is still not full spec.
I've read similar issues here:
https://github.com/swagger-api/swagger-spec/issues/38
https://github.com/mission-liao/pyswagger/issues/18
But I've not found a clear answer.
Source: (StackOverflow)
I have searched and found i have been lost all day now, and I feel I am going round in circles.
I have written, (with help of a few guides), a simple API for my Yii based application.
I have now come to document this API for other to use it.
I read everywhere that Swagger seems to be the way to go to implement, API documentation.
However I can seem to get anywhere on how to use this application
I have followed the instructions on Swagger PHP
Now I am lost has anyone got any examples of what to do next.
I have tried doing some self annotations of my ApiController.php and this doesnt work. I have been trying using the swagger.phar command line, but I still get no where.
I know you will need a lot more information but i dont know what bits of info you need so rather than pasting lots of useless information please ask and i will send anything you need.
To be honest all i would like is some simple API documentation but it just seems impossible.
Cheers
Source: (StackOverflow)
I currently need to document a php project utilizing swagger. However, it does not follow the traditional MVC pattern, and instead, it contains static files that fetch/take-in data and return something.
Resources are created normally inside the json file, however, for some reason, the Models I make are not being rendered. Here is an example of what I would place inside one of my files:
/*@SWG\Resource(
* basePath="mypath",
* resourcePath="/resource",
* produces="['application/json']",
* @SWG\Api(
* path="resource",
* @SWG\Operation(
* method="POST",
* type="void",
* summary="Submit a json thing",
* @SWG\Consumes("application/json"),
* @SWG\Parameter(
* name="body",
* description="The json containing information",
* type="CLASS",
* required=true,
* paramType="body"
* ),
* nickname="resource"
* )
* )
*)
*/
/**
* @SWG\Model(id="CLASS", @SWG\Property(name="name", type="string"))
*/
This Problem Solved The models section is always skipped, and I am unable to get a model schema implemented in my json files.
New Problem I am getting either an out of memory error, or swagger stalls, depending on my server:
On my personal server, when i try to document, it either lags/stalls, and I see no error messages (this does not occur with the example implementation from Swagger-php repository). When I am on the actual server, the out of memory error occurs:
PHP Fatal error: Out of memory (allocated -1202716672) (tried to allocate 261900 bytes) in phar:///usr/local/bin/swagger.phar/library/Swagger/Swagger.php on line 668
Regarding what I use to document this, I use the swagger.phar file from the command line.
Any help regarding how to make models appear would be great. Thank you.
Source: (StackOverflow)