783 lines
41 KiB
HTML
783 lines
41 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>Annotations — Swagger-PHP documentation</title>
|
|
|
|
<link rel="stylesheet" href="static/pyramid.css" type="text/css" />
|
|
<link rel="stylesheet" href="static/pygments.css" type="text/css" />
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: './',
|
|
VERSION: '',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="static/jquery.js"></script>
|
|
<script type="text/javascript" src="static/underscore.js"></script>
|
|
<script type="text/javascript" src="static/doctools.js"></script>
|
|
<link rel="top" title="Swagger-PHP documentation" href="welcome.html" />
|
|
<link rel="next" title="Partials" href="partials.html" />
|
|
<link rel="prev" title="Using Swagger-PHP" href="using_swagger.html" />
|
|
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&subset=latin" type="text/css" media="screen"
|
|
charset="utf-8" />
|
|
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&subset=latin"
|
|
type="text/css" media="screen" charset="utf-8" />
|
|
<!--[if lte IE 6]>
|
|
<link rel="stylesheet" href="static/ie6.css" type="text/css" media="screen" charset="utf-8" />
|
|
<![endif]-->
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="partials.html" title="Partials" accesskey="N">next</a>
|
|
</li>
|
|
<li class="right">
|
|
<a href="using_swagger.html" title="Using Swagger-PHP" accesskey="P">previous</a> |</li>
|
|
<li>
|
|
<a href="welcome.html">Swagger-PHP documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<div class="section" id="annotations">
|
|
<h1>Annotations
|
|
<a class="headerlink" href="#annotations" title="Permalink to this headline">¶</a>
|
|
</h1>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">This is the documentation for (older / unsupported) swagger-php v1.x
|
|
<br>Go to the
|
|
<a href="../">swagger-php v3.x documentation</a>
|
|
</p>
|
|
</div>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="o"><?</span><span class="nx">php</span>
|
|
|
|
<span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> *</span>
|
|
<span class="sd"> * @SWG\Model(id="Pet")</span>
|
|
<span class="sd"> */</span>
|
|
<span class="k">class</span> <span class="nc">Pet</span>
|
|
<span class="p">{</span>
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @var Tag[]</span>
|
|
<span class="sd"> *</span>
|
|
<span class="sd"> * @SWG\Property(name="tags", type="array", items="$ref:Tag")</span>
|
|
<span class="sd"> */</span>
|
|
<span class="k">protected</span> <span class="nv">$tags</span> <span class="o">=</span> <span class="k">array</span><span class="p">();</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>When properties are ommitted, swagger-php will try to detect their value. The name for the @SWGProperty
|
|
in this example is not needed, because swagger-php would infer “tags” based on
|
|
<cite>protected $tags</cite> after the annotation.</p>
|
|
<p>The use statement also optional when using
|
|
<tt class="docutils literal">
|
|
<span class="pre">@SWG\</span>
|
|
</tt> for annotations.</p>
|
|
<p>Tip! Mistype an attribute and a warning will be shown with the available attributes for that particular
|
|
annotation.
|
|
</p>
|
|
<div class="section" id="annotation-hierarchy">
|
|
<h2>Annotation Hierarchy
|
|
<a class="headerlink" href="#annotation-hierarchy" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<div class="highlight-text">
|
|
<div class="highlight">
|
|
<pre>- @SWG\Resource
|
|
- @SWG\Api
|
|
- @SWG\Operation
|
|
- @SWG\Parameter
|
|
- @SWG\ResponseMessage
|
|
|
|
- @SWG\Model
|
|
- @SWG\Property
|
|
- @SWG\Items
|
|
|
|
- @SWG\Authorization
|
|
- @SWG\Scope
|
|
|
|
- @SWG\Info
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="resource">
|
|
<h2>Resource
|
|
<a class="headerlink" href="#resource" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">apiVersion</span>
|
|
</tt> the version this api is being rendered as</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">swaggerVersion</span>
|
|
</tt> the swagger-docs version being rendered
|
|
<tt class="docutils literal">
|
|
<span class="pre">2.0</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">resourcePath</span>
|
|
</tt> the HTTP URI path for the resource</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">basePath</span>
|
|
</tt> the service root HTTP URI path</li>
|
|
<li>
|
|
<a class="reference internal" href="#api">Api</a> []</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Resource(</span>
|
|
<span class="sd"> * apiVersion="0.2",</span>
|
|
<span class="sd"> * swaggerVersion="1.1",</span>
|
|
<span class="sd"> * resourcePath="/pet",</span>
|
|
<span class="sd"> * basePath="http://petstore.swagger.wordnik.com/api"</span>
|
|
<span class="sd"> * )</span>
|
|
<span class="sd"> */</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="p">{</span>
|
|
<span class="s2">"apiVersion"</span><span class="o">:</span><span class="s2">"0.2"</span><span class="p">,</span>
|
|
<span class="s2">"swaggerVersion"</span><span class="o">:</span><span class="s2">"1.1"</span><span class="p">,</span>
|
|
<span class="s2">"basePath"</span><span class="o">:</span><span class="s2">"http://petstore.swagger.wordnik.com/api"</span><span class="p">,</span>
|
|
<span class="s2">"resourcePath"</span><span class="o">:</span><span class="s2">"/pet"</span><span class="p">,</span>
|
|
<span class="s2">"apis"</span><span class="o">:</span><span class="p">[...],</span>
|
|
<span class="s2">"models"</span><span class="o">:</span> <span class="p">[...]</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Recommended as file or class annotation.</p>
|
|
</div>
|
|
<div class="section" id="api">
|
|
<h2>Api
|
|
<a class="headerlink" href="#api" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">path</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">description</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#operation">Operation</a> []</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotation</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> *</span>
|
|
<span class="sd"> * @SWG\Api(</span>
|
|
<span class="sd"> * path="/pet.{format}/{petId}",</span>
|
|
<span class="sd"> * description="Operations about pets",</span>
|
|
<span class="sd"> * @SWG\Operation(...,</span>
|
|
<span class="sd"> * @SWG\Parameter(...),</span>
|
|
<span class="sd"> * @SWG\ResponseMessage(...),</span>
|
|
<span class="sd"> * @SWG\ResponseMessage(...)</span>
|
|
<span class="sd"> * )</span>
|
|
<span class="sd"> * )</span>
|
|
<span class="sd"> */</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="p">{</span>
|
|
<span class="s2">"path"</span><span class="o">:</span><span class="s2">"/pet.{format}/{petId}"</span><span class="p">,</span>
|
|
<span class="s2">"description"</span><span class="o">:</span><span class="s2">"Operations about pets"</span><span class="p">,</span>
|
|
<span class="s2">"operations"</span><span class="o">:</span><span class="p">[</span>
|
|
<span class="p">...</span>
|
|
<span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Must be after or inside a
|
|
<a class="reference internal" href="#resource">Resource</a> annotation. Recommended as method annotation.</p>
|
|
</div>
|
|
<div class="section" id="operation">
|
|
<h2>Operation
|
|
<a class="headerlink" href="#operation" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">method</span>
|
|
</tt> GET|POST|DELETE|PUT|PATCH etc</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">summary</span>
|
|
</tt> string</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">notes</span>
|
|
</tt> string</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">type</span>
|
|
</tt> the
|
|
<a class="reference internal" href="#model">Model</a> ID returned</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">nickname</span>
|
|
</tt> string</li>
|
|
<li>
|
|
<a class="reference internal" href="#responsemessage">ResponseMessage</a> []</li>
|
|
<li>
|
|
<a class="reference internal" href="#parameter">Parameter</a> []</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Operation(</span>
|
|
<span class="sd"> * method="GET", summary="Find pet by ID", notes="Returns a pet based on ID",</span>
|
|
<span class="sd"> * type="Pet", nickname="getPetById", ...</span>
|
|
<span class="sd"> * )</span>
|
|
<span class="sd"> */</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="p">{</span>
|
|
<span class="s2">"method"</span><span class="o">:</span><span class="s2">"GET"</span><span class="p">,</span>
|
|
<span class="s2">"summary"</span><span class="o">:</span><span class="s2">"Find pet by ID"</span><span class="p">,</span>
|
|
<span class="s2">"notes"</span><span class="o">:</span><span class="s2">"Returns a pet based on ID"</span><span class="p">,</span>
|
|
<span class="s2">"type"</span><span class="o">:</span><span class="s2">"Pet"</span><span class="p">,</span>
|
|
<span class="s2">"nickname"</span><span class="o">:</span><span class="s2">"getPetById"</span><span class="p">,</span>
|
|
<span class="s2">"parameters"</span><span class="o">:</span><span class="p">[...],</span>
|
|
<span class="s2">"responseMessages"</span><span class="o">:</span><span class="p">[...]</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Enclosed within
|
|
<a class="reference internal" href="#api">Api</a>.</p>
|
|
</div>
|
|
<div class="section" id="responsemessage">
|
|
<h2>ResponseMessage
|
|
<a class="headerlink" href="#responsemessage" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">code</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">message</span>
|
|
</tt>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\ResponseMessage(code=404, message="Pet not found")</span>
|
|
<span class="sd"> */</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="s2">"responseMessages"</span><span class="o">:</span><span class="p">[</span>
|
|
<span class="p">{</span>
|
|
<span class="s2">"code"</span><span class="o">:</span><span class="mi">404</span><span class="p">,</span>
|
|
<span class="s2">"message"</span><span class="o">:</span><span class="s2">"Pet not found"</span>
|
|
<span class="p">}</span>
|
|
<span class="p">]</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Enclosed within
|
|
<a class="reference internal" href="#operation">Operation</a>.</p>
|
|
</div>
|
|
<div class="section" id="parameter">
|
|
<h2>Parameter
|
|
<a class="headerlink" href="#parameter" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">name</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">description</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">paramType</span>
|
|
</tt> body|query|path</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">required</span>
|
|
</tt> bool</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">allowMultiple</span>
|
|
</tt> bool</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">type</span>
|
|
</tt> scalar or Model|object</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">defaultValue</span>
|
|
</tt>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Parameter(</span>
|
|
<span class="sd"> * name="petId",</span>
|
|
<span class="sd"> * description="ID of pet that needs to be fetched",</span>
|
|
<span class="sd"> * paramType="path",</span>
|
|
<span class="sd"> * required=true,</span>
|
|
<span class="sd"> * allowMultiple=false,</span>
|
|
<span class="sd"> * type="string"</span>
|
|
<span class="sd"> * )</span>
|
|
<span class="sd"> */</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="p">{</span>
|
|
<span class="s2">"name"</span><span class="o">:</span><span class="s2">"petId"</span><span class="p">,</span>
|
|
<span class="s2">"description"</span><span class="o">:</span><span class="s2">"ID of pet that needs to be fetched"</span><span class="p">,</span>
|
|
<span class="s2">"paramType"</span><span class="o">:</span><span class="s2">"path"</span><span class="p">,</span>
|
|
<span class="s2">"required"</span><span class="o">:</span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="s2">"allowMultiple"</span><span class="o">:</span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="s2">"type"</span><span class="o">:</span><span class="s2">"string"</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Enclosed within
|
|
<a class="reference internal" href="#operation">Operation</a>
|
|
</p>
|
|
</div>
|
|
<div class="section" id="model">
|
|
<h2>Model
|
|
<a class="headerlink" href="#model" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The annotations parser will follow any
|
|
<cite>extend</cite> statements of the current model class and include annotations from the
|
|
base class as well, as long as the
|
|
<tt class="docutils literal">
|
|
<span class="pre">Model</span>
|
|
</tt> annotation is placed into the comment block directly above the class declaration. Be
|
|
sure also to activate the parser in the base class with the appropriate annotations.</p>
|
|
</div>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">id</span>
|
|
</tt> the formal name of the Model being described. Defaults to the name of the class (excl.
|
|
namespace).
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">required</span>
|
|
</tt> the required properties. Example: required=”[‘id’,’name’]”</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Model(id="Pet")</span>
|
|
<span class="sd"> */</span>
|
|
<span class="k">class</span> <span class="nc">Pet</span>
|
|
<span class="p">{</span>
|
|
<span class="o">...</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="s2">"Pet"</span><span class="o">:</span><span class="p">{</span>
|
|
<span class="s2">"id"</span><span class="o">:</span><span class="s2">"Pet"</span><span class="p">,</span>
|
|
<span class="s2">"properties"</span><span class="o">:</span><span class="p">{</span>
|
|
<span class="p">...</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="property">
|
|
<h2>Property
|
|
<a class="headerlink" href="#property" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">name</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">type</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">description</span>
|
|
</tt>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#items">Items</a>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Property(name="category",type="Category")</span>
|
|
<span class="sd"> */</span>
|
|
<span class="k">public</span> <span class="nv">$category</span><span class="p">;</span>
|
|
<span class="o">*</span> <span class="o">@</span><span class="nx">SWG\Property</span><span class="p">(</span>
|
|
<span class="o">*</span> <span class="nx">name</span><span class="o">=</span><span class="s2">"status"</span><span class="p">,</span><span class="nx">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span>
|
|
<span class="o">*</span> <span class="nx">enum</span><span class="o">=</span><span class="s2">"['available', 'pending', 'sold']"</span><span class="p">,</span>
|
|
<span class="o">*</span> <span class="nx">description</span><span class="o">=</span><span class="s2">"pet status in the store"</span><span class="p">)</span>
|
|
<span class="o">*/</span>
|
|
<span class="k">public</span> <span class="nv">$status</span><span class="p">;</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre><span class="s2">"category"</span><span class="o">:</span><span class="p">{</span>
|
|
<span class="s2">"type"</span><span class="o">:</span><span class="s2">"Category"</span>
|
|
<span class="p">},</span>
|
|
<span class="s2">"status"</span><span class="o">:</span><span class="p">{</span>
|
|
<span class="s2">"enum"</span><span class="o">:</span><span class="p">[</span><span class="s2">"available"</span><span class="p">,</span> <span class="s2">"pending"</span><span class="p">,</span> <span class="s2">"sold"</span><span class="p">],</span>
|
|
<span class="s2">"description"</span><span class="o">:</span><span class="s2">"pet status in the store"</span><span class="p">,</span>
|
|
<span class="s2">"type"</span><span class="o">:</span><span class="s2">"string"</span>
|
|
<span class="p">},</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Enclosed within
|
|
<a class="reference internal" href="#model">Model</a> or as property annotation.</p>
|
|
</div>
|
|
<div class="section" id="items">
|
|
<h2>Items
|
|
<a class="headerlink" href="#items" title="Permalink to this headline">¶</a>
|
|
</h2>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The
|
|
<tt class="docutils literal">
|
|
<span class="pre">Items</span>
|
|
</tt> annotation defines an array type i.e. an array of integers, strings or
|
|
<tt class="docutils literal">
|
|
<span class="pre">$ref</span>
|
|
</tt> to another model type. References are defined with a
|
|
<strong>$ref:</strong> preamble followed by the model ID name as defined within a
|
|
<a class="reference internal" href="#model">Model</a> annotation. The
|
|
<tt class="docutils literal">
|
|
<span class="pre">@SWG\Items</span>
|
|
</tt> annotation resides within a
|
|
<a class="reference internal" href="#property">Property</a> declaration.</p>
|
|
</div>
|
|
<p>
|
|
<strong>Attributes</strong>
|
|
</p>
|
|
<ul class="simple">
|
|
<li>
|
|
<tt class="docutils literal">
|
|
<span class="pre">Type</span>
|
|
</tt>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<strong>Example Annotations</strong>
|
|
</p>
|
|
<div class="highlight-php">
|
|
<div class="highlight">
|
|
<pre><span class="k">use</span> <span class="nx">Swagger\Annotations</span> <span class="k">as</span> <span class="nx">SWG</span><span class="p">;</span>
|
|
|
|
<span class="k">class</span> <span class="nc">Pet</span>
|
|
<span class="p">{</span>
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Property(name="photoUrls",type="array",@SWG\Items("string"))</span>
|
|
<span class="sd"> */</span>
|
|
<span class="k">public</span> <span class="nv">$photos</span><span class="p">;</span>
|
|
|
|
<span class="sd">/**</span>
|
|
<span class="sd"> * @SWG\Property(name="tags",type="array",@SWG\Items("Tag"))</span>
|
|
<span class="sd"> */</span>
|
|
<span class="k">public</span> <span class="nv">$tags</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Derived JSON</strong>
|
|
</p>
|
|
<div class="highlight-javascript">
|
|
<div class="highlight">
|
|
<pre>"properties":{
|
|
"tags":{
|
|
"items":{
|
|
"$ref":"Tag"
|
|
},
|
|
"type":"array"
|
|
},
|
|
"id":{
|
|
"type":"integer",
|
|
"format: "int64"
|
|
},
|
|
"category":{
|
|
"type":"Category"
|
|
},
|
|
"status":{
|
|
"enum":["available", "pending", "sold"]
|
|
"description":"pet status in the store",
|
|
"type":"string"
|
|
},
|
|
"name":{
|
|
"type":"string"
|
|
},
|
|
"photoUrls":{
|
|
"items":{
|
|
"type":"string"
|
|
},
|
|
"type":"array"
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
<strong>Allowable Use:</strong>
|
|
</p>
|
|
<p>Enclosed within:
|
|
<a class="reference internal" href="#property">Property</a>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h3>
|
|
<a href="welcome.html">Table Of Contents</a>
|
|
</h3>
|
|
<ul>
|
|
<li>
|
|
<a class="reference internal" href="#">Annotations</a>
|
|
<ul>
|
|
<li>
|
|
<a class="reference internal" href="#annotation-hierarchy">Annotation Hierarchy</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#resource">Resource</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#api">Api</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#operation">Operation</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#responsemessage">ResponseMessage</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#parameter">Parameter</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#model">Model</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#property">Property</a>
|
|
</li>
|
|
<li>
|
|
<a class="reference internal" href="#items">Items</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless">
|
|
<a href="using_swagger.html" title="previous chapter">Using Swagger-PHP</a>
|
|
</p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless">
|
|
<a href="partials.html" title="next chapter">Partials</a>
|
|
</p>
|
|
<div id="searchbox" style="display: none">
|
|
<h3>Quick search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
<p class="searchtip" style="font-size: 90%">
|
|
Enter search terms or a module, class or function name.
|
|
</p>
|
|
</div>
|
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="partials.html" title="Partials">next</a>
|
|
</li>
|
|
<li class="right">
|
|
<a href="using_swagger.html" title="Using Swagger-PHP">previous</a> |</li>
|
|
<li>
|
|
<a href="welcome.html">Swagger-PHP documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© Copyright 2014, Robert Allen & Bob Fanger. Created using
|
|
<a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
|
|
</div>
|
|
</body>
|
|
|
|
</html> |