Swagger Petstore OpenAPI 3.0 example

This page renders the Swagger Petstore - OpenAPI 3.0 sample API. It describes the same pets, store orders, and users as the Swagger 2.0 Petstore example, but uses OpenAPI 3.0 with reusable components, request bodies in several media types, and enums.

The page needs only this front matter:

---
openapi: ./openapi-petstore-v3.json
---

openapi-petstore-v3.json is the specification from https://petstore3.swagger.io/api/v3/openapi.json, formatted with indentation. The specification declares the Apache License 2.0.

API overview

Swagger Petstore - OpenAPI 3.0

Version 1.0.27

License Apache 2.0Contact apiteam@swagger.io Terms of service

This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about Swagger at https://swagger.io. In the third iteration of the pet store, we've switched to the design first approach! You can now help us improve the API whether it's by making changes to the definition itself or to the code. That way, with time, we can improve the API in general, and expose some of the new features in OAS3.

Some useful links:

Server

/api/v3

Authentication

petstore_authOAuth 2.0
api_keyAPI key api_key in header

pet3 3 1 1 Everything about your Pets

GET /pet/findByStatus Finds Pets by status.

Operation ID findPetsByStatus

Multiple status values can be provided with comma separated strings.

Authorization

petstore_authOAuth 2.0write:petsread:pets

Query Parameters

Parameter	Description
status: string = "available"`availablependingsold`	Status values that need to be considered for filter

Response 1 of 3

successful operation

Media Type 1 of 2

GET /pet/findByTags Finds Pets by tags.

Operation ID findPetsByTags

Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.

Authorization

petstore_authOAuth 2.0write:petsread:pets

Query Parameters

Parameter	Description
tags: [string]	Tags to filter by

Response 1 of 3

successful operation

Media Type 1 of 2

GET /pet/{petId} Find pet by ID.

Operation ID getPetById

Returns a single pet.

Authorization

api_keyAPI key api_key in header
petstore_authOAuth 2.0write:petsread:pets

Path Parameters

Parameter	Description
petId: int64	ID of pet to return

Response 1 of 4

successful operation

Media Type 1 of 2

POST /pet Add a new pet to the store.

Operation ID addPet

Authorization

petstore_authOAuth 2.0write:petsread:pets

Request body Required

Create a new pet in the store

Media Type 1 of 3

Response 1 of 4

Successful operation

Media Type 1 of 2

POST /pet/{petId} Updates a pet in the store with form data.

Operation ID updatePetWithForm

Updates a pet resource based on the form data.

Authorization

petstore_authOAuth 2.0write:petsread:pets

Path Parameters

Parameter	Description
petId: int64	ID of pet that needs to be updated

Query Parameters

Parameter	Description
name: string	Name of pet that needs to be updated
status: string	Status of pet that needs to be updated

Response 1 of 3

successful operation

Media Type 1 of 2

POST /pet/{petId}/uploadImage Uploads an image.

Operation ID uploadFile

Upload image of the pet.

Authorization

petstore_authOAuth 2.0write:petsread:pets

Path Parameters

Parameter	Description
petId: int64	ID of pet to update

Query Parameters

Parameter	Description
additionalMetadata: string	Additional Metadata

Request body

Media Type 1 of 1

binary

string

binary

Property	Description
value: binary

binary

{
  "type": "string",
  "format": "binary"
}

Response 1 of 4

successful operation

Media Type 1 of 1

ApiResponse

{
  "code": 0,
  "type": "string",
  "message": "string"
}

ApiResponse

Property	Description
code: int32
type: string
message: string

ApiResponse

{
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "format": "int32"
    },
    "type": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "xml": {
    "name": "##default"
  }
}

PUT /pet Update an existing pet.

Operation ID updatePet

Update an existing pet by Id.

Authorization

petstore_authOAuth 2.0write:petsread:pets

Request body Required

Update an existent pet in the store

Media Type 1 of 3

Response 1 of 5

Successful operation

Media Type 1 of 2

DELETE /pet/{petId} Deletes a pet.

Operation ID deletePet

Delete a pet.

Authorization

petstore_authOAuth 2.0write:petsread:pets

Path Parameters

Parameter	Description
petId: int64	Pet id to delete

Header Parameters

Parameter	Description
api_key: string

Response 1 of 3

Pet deleted

store2 1 1 Access to Petstore orders

GET /store/inventory Returns pet inventories by status.

Operation ID getInventory

Returns a map of status codes to quantities.

Authorization

api_keyAPI key api_key in header

Response 1 of 2

successful operation

Media Type 1 of 1

[string: int32]

{
  "additionalProp1": 0
}

[string: int32]

Property	Description
value: [string: int32]

[string: int32]

{
  "type": "object",
  "additionalProperties": {
    "type": "integer",
    "format": "int32"
  }
}

GET /store/order/{orderId}Find purchase order by ID.

Operation ID getOrderById

For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.

Path Parameters

Parameter	Description
orderId: int64	ID of order that needs to be fetched

Response 1 of 4

successful operation

Media Type 1 of 2

POST /store/orderPlace an order for a pet.

Operation ID placeOrder

Place a new order in the store.

Request body

Media Type 1 of 3

Response 1 of 4

successful operation

Media Type 1 of 1

DELETE /store/order/{orderId}Delete purchase order by identifier.

Operation ID deleteOrder

For valid response try integer IDs with value < 1000. Anything above 1000 or non-integers will generate API errors.

Path Parameters

Parameter	Description
orderId: int64	ID of the order that needs to be deleted

Response 1 of 4

order deleted

user3 2 1 1 Operations about user

GET /user/loginLogs user into the system.

Operation ID loginUser

Log into the system.

Query Parameters

Parameter	Description
username: string	The user name for login
password: string	The password for login in clear text

Response 1 of 3

successful operation

Response headers

Header	Description
X-Rate-Limit: int32	calls per hour allowed by the user
X-Expires-After: dateTime	date in UTC when token expires

Media Type 1 of 2

string

string

GET /user/logoutLogs out current logged in user session.

Operation ID logoutUser

Log user out of the system.

Response 1 of 2

successful operation

GET /user/{username}Get user by user name.

Operation ID getUserByName

Get user detail based on username.

Path Parameters

Parameter	Description
username: string	The name that needs to be fetched. Use user1 for testing

Response 1 of 4

successful operation

Media Type 1 of 2

POST /userCreate user.

Operation ID createUser

This can only be done by the logged in user.

Request body

Created user object

Media Type 1 of 3

Response 1 of 2

successful operation

Media Type 1 of 2

POST /user/createWithListCreates list of users with given input array.

Operation ID createUsersWithListInput

Request body

Media Type 1 of 1

[User]

[
  {
    "id": 10,
    "username": "theUser",
    "firstName": "John",
    "lastName": "James",
    "email": "john@email.com",
    "password": "12345",
    "phone": "12345",
    "userStatus": 1
  }
]

[User]

Property	Description
id: int64
username: string
firstName: string
lastName: string
email: string
password: string
phone: string
userStatus: int32	User Status

[User]

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/User"
  }
}

User

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "example": 10
    },
    "username": {
      "type": "string",
      "example": "theUser"
    },
    "firstName": {
      "type": "string",
      "example": "John"
    },
    "lastName": {
      "type": "string",
      "example": "James"
    },
    "email": {
      "type": "string",
      "example": "john@email.com"
    },
    "password": {
      "type": "string",
      "example": "12345"
    },
    "phone": {
      "type": "string",
      "example": "12345"
    },
    "userStatus": {
      "type": "integer",
      "description": "User Status",
      "format": "int32",
      "example": 1
    }
  },
  "xml": {
    "name": "user"
  }
}

Response 1 of 2

Successful operation

Media Type 1 of 2

PUT /user/{username}Update user resource.

Operation ID updateUser

This can only be done by the logged in user.

Path Parameters

Parameter	Description
username: string	name that need to be deleted

Request body

Update an existent user in the store

Media Type 1 of 3

Response 1 of 4

successful operation

DELETE /user/{username}Delete user resource.

Operation ID deleteUser

This can only be done by the logged in user.

Path Parameters

Parameter	Description
username: string	The name that needs to be deleted

Response 1 of 4

User deleted

Property	Description
id: int64
name: string
category: Category
photoUrls: [string]
tags: [Tag]
status: string`availablependingsold`	pet status in the store

Property	Description
id: int64
name: string
category: Category
photoUrls: [string]
tags: [Tag]
status: string`availablependingsold`	pet status in the store

Property	Description
id: int64
petId: int64
quantity: int32
shipDate: dateTime
status: string`placedapproveddelivered`	Order Status
complete: boolean

Swagger Petstore OpenAPI 3.0 example

API overview

`Category`

`Tag`

`Category`

`Tag`

Search documentation

Media settings