= Swagger Petstore


[[_overview]]
== Overview
This is a sample server Petstore server.

http://swagger.io[Learn about Swagger] or join the IRC channel `#swagger` on irc.freenode.net.

For this sample, you can use the api key `special-key` to test the authorization filters


=== Version information
[%hardbreaks]
__Version__ : 1.0.0


=== Contact information
[%hardbreaks]
__Contact__ : apiteam@swagger.io


=== License information
[%hardbreaks]
__License__ : Apache 2.0
__License URL__ : http://www.apache.org/licenses/LICENSE-2.0.html
__Terms of service__ : http://helloreverb.com/terms/


=== URI scheme
[%hardbreaks]
__Host__ : petstore.swagger.io
__BasePath__ : /v2
__Schemes__ : HTTP


=== Tags

* pet : Pet resource
* store : Store resource
* user : User resource


=== External Docs
[%hardbreaks]
__Description__ : Find out more about Swagger
__URL__ : http://swagger.io




[[_paths]]
== Paths

[[_addpet]]
=== Add a new pet to the store
....
POST /pets
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**body** +
__optional__|Pet object that needs to be added to the store|<<_pet,Pet>>
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**405**|Invalid input|No Content
|===


==== Consumes

* `application/json`
* `application/xml`


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_updatepet]]
=== Update an existing pet
....
PUT /pets
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**body** +
__optional__|Pet object that needs to be added to the store|<<_pet,Pet>>
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**400**|Invalid ID supplied|No Content
|**404**|Pet not found|No Content
|**405**|Validation exception|No Content
|===


==== Consumes

* `application/json`
* `application/xml`


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_findpetsbystatus]]
=== Finds Pets by status
....
GET /pets/findByStatus
....


==== Description
Multiple status values can be provided with comma seperated strings


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Query**|**status** +
__optional__|Status values that need to be considered for filter|< string > array(multi)
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|< <<_pet,Pet>> > array
|**400**|Invalid status value|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_findpetsbytags]]
=== Finds Pets by tags
....
GET /pets/findByTags
....


==== Description
Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Query**|**tags** +
__optional__|Tags to filter by|< string > array(multi)
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|< <<_pet,Pet>> > array
|**400**|Invalid tag value|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_updatepetwithform]]
=== Updates a pet in the store with form data
....
POST /pets/{petId}
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**petId** +
__required__|ID of pet that needs to be updated|string
|**FormData**|**name** +
__required__|Updated name of the pet|string
|**FormData**|**status** +
__required__|Updated status of the pet|string
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**405**|Invalid input|No Content
|===


==== Consumes

* `application/x-www-form-urlencoded`


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_getpetbyid]]
=== Find pet by ID
....
GET /pets/{petId}
....


==== Description
Returns a pet when ID &lt; 10. ID &gt; 10 or nonintegers will simulate API error conditions


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**petId** +
__required__|ID of pet that needs to be fetched|integer (int64)
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|<<_pet,Pet>>
|**400**|Invalid ID supplied|No Content
|**404**|Pet not found|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**apiKey**|**<<_api_key,api_key>>**|
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_deletepet]]
=== Deletes a pet
....
DELETE /pets/{petId}
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Header**|**api_key** +
__required__||string
|**Path**|**petId** +
__required__|Pet id to delete|integer (int64)
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**400**|Invalid pet value|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* pet


==== Security

[options="header", cols=".^3a,.^4a,.^13a"]
|===
|Type|Name|Scopes
|**oauth2**|**<<_petstore_auth,petstore_auth>>**|write_pets,read_pets
|===


[[_placeorder]]
=== Place an order for a pet
....
POST /stores/order
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**body** +
__optional__|order placed for purchasing the pet|<<_order,Order>>
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|<<_order,Order>>
|**400**|Invalid Order|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* store


[[_getorderbyid]]
=== Find purchase order by ID
....
GET /stores/order/{orderId}
....


==== Description
For valid response try integer IDs with value &lt;= 5 or &gt; 10. Other values will generated exceptions


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**orderId** +
__required__|ID of pet that needs to be fetched|string
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|<<_order,Order>>
|**400**|Invalid ID supplied|No Content
|**404**|Order not found|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* store


[[_deleteorder]]
=== Delete purchase order by ID
....
DELETE /stores/order/{orderId}
....


==== Description
For valid response try integer IDs with value &lt; 1000. Anything above 1000 or nonintegers will generate API errors


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**orderId** +
__required__|ID of the order that needs to be deleted|string
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**400**|Invalid ID supplied|No Content
|**404**|Order not found|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* store


[[_createuser]]
=== Create user
....
POST /users
....


==== Description
This can only be done by the logged in user.


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**body** +
__optional__|Created user object|<<_user,User>>
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**default**|successful operation|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_createuserswitharrayinput]]
=== Creates list of users with given input array
....
POST /users/createWithArray
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**body** +
__optional__|List of user object|< <<_user,User>> > array
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**default**|successful operation|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_createuserswithlistinput]]
=== Creates list of users with given input array
....
POST /users/createWithList
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Body**|**body** +
__optional__|List of user object|< <<_user,User>> > array
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**default**|successful operation|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_loginuser]]
=== Logs user into the system
....
GET /users/login
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Query**|**password** +
__optional__|The password for login in clear text|string
|**Query**|**username** +
__optional__|The user name for login|string
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|string
|**400**|Invalid username/password supplied|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_logoutuser]]
=== Logs out current logged in user session
....
GET /users/logout
....


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**default**|successful operation|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_getuserbyname]]
=== Get user by user name
....
GET /users/{username}
....


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**username** +
__required__|The name that needs to be fetched. Use user1 for testing.|string
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**200**|successful operation +
**Headers** :  +
`X-Rate-Limit-Limit` (integer) : The number of allowed requests in the current period. +
`X-Rate-Limit-Remaining` (integer) : The number of remaining requests in the current period. +
`X-Rate-Limit-Reset` (integer) : The number of seconds left in the current period.|<<_user,User>>
|**400**|Invalid username supplied|No Content
|**404**|User not found|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_updateuser]]
=== Updated user
....
PUT /users/{username}
....


==== Description
This can only be done by the logged in user.


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**username** +
__required__|name that need to be deleted|string
|**Body**|**body** +
__optional__|Updated user object|<<_user,User>>
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**400**|Invalid user supplied|No Content
|**404**|User not found|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user


[[_deleteuser]]
=== Delete user
....
DELETE /users/{username}
....


==== Description
This can only be done by the logged in user.


==== Parameters

[options="header", cols=".^2a,.^3a,.^9a,.^4a"]
|===
|Type|Name|Description|Schema
|**Path**|**username** +
__required__|The name that needs to be deleted|string
|===


==== Responses

[options="header", cols=".^2a,.^14a,.^4a"]
|===
|HTTP Code|Description|Schema
|**400**|Invalid username supplied|No Content
|**404**|User not found|No Content
|===


==== Produces

* `application/json`
* `application/xml`


==== Tags

* user




[[_definitions]]
== Definitions

[[_category]]
=== Category

[options="header", cols=".^3a,.^11a,.^4a"]
|===
|Name|Description|Schema
|**id** +
__optional__||integer (int64)
|**name** +
__optional__|The name of the category +
**Default** : `"DefaultCategory"` +
**Length** : `0 - 255` +
**Pattern** : `"[A-Za-zäöüÄÖÜß]{0,255}"` +
**Example** : `"FoobarCategory"`|string
|===


[[_order]]
=== Order

[options="header", cols=".^3a,.^11a,.^4a"]
|===
|Name|Description|Schema
|**complete** +
__optional__||boolean
|**id** +
__optional__||integer (int64)
|**petId** +
__optional__||integer (int64)
|**quantity** +
__optional__|**Default** : `0` +
**Minimum value** : `0` +
**Maximum value** : `10000` +
**Example** : `10`|integer (int32)
|**shipDate** +
__optional__||string (date-time)
|**status** +
__optional__|Order Status|enum (Ordered, Cancelled)
|===


[[_pet]]
=== Pet

[options="header", cols=".^3a,.^11a,.^4a"]
|===
|Name|Description|Schema
|**category** +
__optional__||<<_category,Category>>
|**id** +
__optional__||integer (int64)
|**name** +
__required__|**Example** : `"doggie"`|string
|**photoUrls** +
__required__||< string > array
|**status** +
__optional__|pet status in the store,|enum (Dead, Alive)
|**tags** +
__optional__||< <<_tag,Tag>> > array
|===


[[_tag]]
=== Tag

[options="header", cols=".^3a,.^4a"]
|===
|Name|Schema
|**id** +
__optional__|integer (int64)
|**name** +
__optional__|string
|===


[[_user]]
=== User

[options="header", cols=".^3a,.^11a,.^4a"]
|===
|Name|Description|Schema
|**email** +
__optional__||string
|**firstName** +
__optional__||string
|**id** +
__optional__||integer (int64)
|**lastName** +
__optional__||string
|**password** +
__optional__||string
|**phone** +
__optional__||string
|**userStatus** +
__optional__|User Status|integer (int32)
|**username** +
__optional__||string
|===




[[_securityscheme]]
== Security

[[_api_key]]
=== api_key
This is another description

[%hardbreaks]
__Type__ : apiKey
__Name__ : api_key
__In__ : HEADER


[[_petstore_auth]]
=== petstore_auth
This is a standard oauth flow

[%hardbreaks]
__Type__ : oauth2
__Flow__ : implicit
__Token URL__ : http://petstore.swagger.io/api/oauth/dialog


[options="header", cols=".^3a,.^17a"]
|===
|Name|Description
|write_pets|modify pets in your account
|read_pets|read your pets
|===



