Created
October 1, 2018 13:39
-
-
Save predic8/a0e0e65c63dea67d9396bb24c0f18840 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
swagger: '2.0' | |
host: 'api.predic8.de:443' | |
basePath: /shop | |
schemes: | |
- https | |
info: | |
title: Fruit Shop API | |
version: 1.0.0 | |
description: >- | |
This is a showcase for REST API design and serves as a public API for | |
educational usage. | |
contact: | |
name: Thomas Bayer | |
url: 'http://predic8.de' | |
email: bayer@predic8.de | |
tags: | |
- name: categories | |
- name: customers | |
- name: orders | |
- name: products | |
- name: vendors | |
paths: | |
/categories/: | |
get: | |
summary: Lists all the product categories | |
operationId: getShopCategories | |
tags: | |
- categories | |
responses: | |
'200': | |
description: List of categories | |
schema: | |
$ref: '#/definitions/CategoryList' | |
'/categories/{id}': | |
get: | |
summary: Get a category by id | |
operationId: getShopCategoriesId | |
parameters: | |
- type: string | |
description: Id of a category | |
name: id | |
in: path | |
required: true | |
tags: | |
- categories | |
responses: | |
'200': | |
description: Collection of products | |
schema: | |
$ref: '#/definitions/ProductList' | |
'/customers/{id}': | |
get: | |
summary: Get a customer by id | |
operationId: getShopCustomersId | |
parameters: | |
- type: integer | |
description: Id of a customer | |
name: id | |
in: path | |
required: true | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Customer details | |
schema: | |
$ref: '#/definitions/Customer' | |
put: | |
summary: Replace a customer by new data | |
operationId: putShopCustomersId | |
parameters: | |
- type: integer | |
description: Id of a customer | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/Customer' | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Customer details | |
schema: | |
$ref: '#/definitions/Customer' | |
patch: | |
summary: Update a customer | |
operationId: patchShopCustomersId | |
parameters: | |
- type: integer | |
description: Id of a customer | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/CustomerPatch' | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Customer details | |
schema: | |
$ref: '#/definitions/Customer' | |
delete: | |
summary: Delete a customer | |
operationId: deleteShopCustomersId | |
parameters: | |
- type: integer | |
description: Id of a customer | |
name: id | |
in: path | |
required: true | |
tags: | |
- customers | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
/customers/: | |
get: | |
summary: Lists all the customers | |
operationId: getShopCustomers | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Collection of customers | |
schema: | |
$ref: '#/definitions/CustomerList' | |
post: | |
summary: Create a customer | |
operationId: postShopCustomers | |
parameters: | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/Customer' | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Customer details | |
schema: | |
$ref: '#/definitions/Customer' | |
'/orders/{id}': | |
get: | |
summary: Get an order by id | |
operationId: getShopOrdersId | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: id | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
'200': | |
description: Order details | |
schema: | |
$ref: '#/definitions/Order' | |
delete: | |
summary: Delete an order | |
operationId: deleteShopOrdersId | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: id | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
/orders/: | |
get: | |
summary: Lists all the orders | |
operationId: getShopOrders | |
parameters: | |
- type: string | |
description: State of the order | |
enum: | |
- created | |
- ordered | |
- delivered | |
- canceled | |
name: state | |
in: query | |
tags: | |
- orders | |
responses: | |
'200': | |
description: Collection of orders | |
schema: | |
$ref: '#/definitions/OrderList' | |
'/products/{id}': | |
get: | |
summary: Get a product by id | |
operationId: getShopProductsId | |
parameters: | |
- type: integer | |
description: Id of a product | |
name: id | |
in: path | |
required: true | |
tags: | |
- products | |
responses: | |
'200': | |
description: Product description | |
schema: | |
$ref: '#/definitions/Product' | |
put: | |
summary: Replace a product by new data | |
operationId: putShopProductsId | |
parameters: | |
- type: integer | |
description: Id of a product | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/Product' | |
tags: | |
- products | |
responses: | |
'200': | |
description: Product description | |
schema: | |
$ref: '#/definitions/Product' | |
patch: | |
summary: Update one or more properties of a product | |
operationId: patchShopProductsId | |
parameters: | |
- type: integer | |
description: Id of a product | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/ProductPatch' | |
tags: | |
- products | |
responses: | |
'200': | |
description: Product description | |
schema: | |
$ref: '#/definitions/Product' | |
delete: | |
summary: Delete a product | |
operationId: deleteShopProductsId | |
parameters: | |
- type: integer | |
description: Id of a product | |
name: id | |
in: path | |
required: true | |
tags: | |
- products | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
/products/: | |
get: | |
summary: Lists all the products | |
operationId: getShopProducts | |
tags: | |
- products | |
responses: | |
'200': | |
description: Collection of products | |
schema: | |
$ref: '#/definitions/ProductList' | |
post: | |
summary: Create a product | |
operationId: postShopProducts | |
parameters: | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/Product' | |
tags: | |
- products | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
'/vendors/{id}': | |
get: | |
summary: Get a vendor by id | |
operationId: getShopVendorsId | |
parameters: | |
- type: integer | |
description: Id of a vendor | |
name: id | |
in: path | |
required: true | |
tags: | |
- vendors | |
responses: | |
'200': | |
description: Vendor of products | |
schema: | |
$ref: '#/definitions/Vendor' | |
put: | |
summary: Replace a vendor by new data | |
operationId: putShopVendorsId | |
parameters: | |
- type: integer | |
description: Id of a vendor | |
name: id | |
in: path | |
required: true | |
tags: | |
- vendors | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
patch: | |
summary: Update a vendor | |
operationId: patchShopVendorsId | |
parameters: | |
- type: integer | |
description: Id of a vendor | |
name: id | |
in: path | |
required: true | |
tags: | |
- vendors | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
delete: | |
summary: Delete a vendor | |
operationId: deleteShopVendorsId | |
parameters: | |
- type: integer | |
description: Id of a vendor | |
name: id | |
in: path | |
required: true | |
tags: | |
- vendors | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
/vendors/: | |
get: | |
summary: Lists all the vendors | |
operationId: getShopVendors | |
tags: | |
- vendors | |
responses: | |
'200': | |
description: Collection of vendors | |
schema: | |
$ref: '#/definitions/VendorList' | |
post: | |
summary: Create a vendor | |
operationId: postShopVendors | |
parameters: | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/Vendor' | |
tags: | |
- vendors | |
responses: | |
'200': | |
description: Vendor of products | |
schema: | |
$ref: '#/definitions/Vendor' | |
'/products/{id}/photo': | |
get: | |
summary: Get a photo of a product | |
operationId: getShopProductsIdPhoto | |
parameters: | |
- type: integer | |
description: Id of a product | |
name: id | |
in: path | |
required: true | |
tags: | |
- products | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
put: | |
summary: Add or update the photo of a product | |
operationId: putShopProductsIdPhoto | |
description: Length of the image is limited to 512 KBytes. | |
parameters: | |
- type: integer | |
description: Id of a product | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/ProductImage' | |
consumes: | |
- multipart/form-data | |
tags: | |
- products | |
responses: | |
'200': | |
description: Product description | |
schema: | |
$ref: '#/definitions/Product' | |
'/customers/{id}/orders/': | |
get: | |
summary: Get the orders of a customer | |
operationId: getShopCustomersIdOrders | |
parameters: | |
- type: integer | |
description: Id of a customer | |
name: id | |
in: path | |
required: true | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Collection of orders | |
schema: | |
$ref: '#/definitions/OrderList' | |
post: | |
summary: Create an order for a customer | |
operationId: postShopCustomersIdOrders | |
parameters: | |
- type: integer | |
description: Id of a customer | |
name: id | |
in: path | |
required: true | |
tags: | |
- customers | |
responses: | |
'200': | |
description: Order details | |
schema: | |
$ref: '#/definitions/Order' | |
'/orders/{id}/items/': | |
get: | |
summary: Get the items of an order | |
operationId: getShopOrdersIdItems | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: id | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
'200': | |
description: Collection of items | |
schema: | |
$ref: '#/definitions/Items' | |
post: | |
summary: Add an item to an order | |
operationId: postShopOrdersIdItems | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/Item' | |
tags: | |
- orders | |
responses: | |
'200': | |
description: Item details | |
schema: | |
$ref: '#/definitions/Item' | |
'/orders/{oid}/items/{iid}': | |
get: | |
summary: Get an item of an order | |
operationId: getShopOrdersOidItemsIid | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: oid | |
in: path | |
required: true | |
- type: integer | |
description: Id of an item | |
name: iid | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
'200': | |
description: Item details | |
schema: | |
$ref: '#/definitions/Item' | |
delete: | |
summary: Delete an item of an order | |
operationId: deleteShopOrdersOidItemsIid | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: oid | |
in: path | |
required: true | |
- type: integer | |
description: Id of an item | |
name: iid | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
'/vendors/{id}/products/': | |
get: | |
summary: Get the products of a vendor | |
operationId: getShopVendorsIdProducts | |
parameters: | |
- type: integer | |
description: Id of a vendor | |
name: id | |
in: path | |
required: true | |
tags: | |
- vendors | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
post: | |
summary: Add a product to a vendor | |
operationId: postShopVendorsIdProducts | |
parameters: | |
- type: integer | |
description: Id of a vendor | |
name: id | |
in: path | |
required: true | |
- in: body | |
name: body | |
schema: | |
$ref: '#/definitions/NamePriceCategory' | |
tags: | |
- vendors | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
'/orders/{id}/actions/purchase': | |
post: | |
summary: Purchase an order | |
operationId: postShopOrdersIdActionsPurchase | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: id | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
'/orders/{id}/actions/cancel': | |
post: | |
summary: Cancel an order | |
operationId: postShopOrdersIdActionsCancel | |
parameters: | |
- type: integer | |
description: Id of an order | |
name: id | |
in: path | |
required: true | |
tags: | |
- orders | |
responses: | |
default: | |
schema: | |
type: string | |
description: Successful | |
definitions: | |
CategoryEntry: | |
type: object | |
description: Category entry | |
x-meta: | |
className: CategoryEntry | |
properties: | |
name: | |
type: string | |
description: Name of the category | |
example: Fruits | |
category_url: | |
type: string | |
example: /shop/categories/Fruits | |
required: | |
- name | |
categories: | |
type: array | |
items: | |
$ref: '#/definitions/CategoryEntry' | |
CategoryList: | |
type: object | |
description: List of categories | |
x-meta: | |
className: CategoryList | |
properties: | |
categories: | |
$ref: '#/definitions/categories' | |
Meta: | |
type: object | |
description: Metadata about a collection of resources. | |
x-meta: | |
className: Meta | |
properties: | |
count: | |
type: integer | |
description: Total number of entries | |
example: 22 | |
limit: | |
type: integer | |
description: How many entries are delivered in one response | |
example: 10 | |
page: | |
type: integer | |
description: Number of the page within the results | |
example: 2 | |
previous_url: | |
type: string | |
description: URL to the previous page of results | |
example: /shop/products/?page=1&limit=10 | |
next_url: | |
type: string | |
description: URL to the next page of results | |
example: /shop/products/?page=3&limit=10 | |
required: | |
- count | |
ProductEntry: | |
type: object | |
description: Entry of a product collection | |
example: | |
name: Pineapples | |
product_url: /shop/products/33 | |
x-meta: | |
className: ProductEntry | |
properties: | |
name: | |
type: string | |
description: Name of the product | |
product_url: | |
type: string | |
required: | |
- name | |
products: | |
type: array | |
items: | |
$ref: '#/definitions/ProductEntry' | |
ProductList: | |
type: object | |
description: Collection of products | |
x-meta: | |
className: ProductList | |
properties: | |
meta: | |
$ref: '#/definitions/Meta' | |
products: | |
$ref: '#/definitions/products' | |
Customer: | |
type: object | |
description: Customer details | |
example: | |
firstname: Freddy | |
lastname: Meyers | |
x-meta: | |
className: Customer | |
properties: | |
firstname: | |
type: string | |
example: Fred | |
lastname: | |
type: string | |
example: Meyers | |
orders_url: | |
type: string | |
description: Link to the orders of the customer | |
customer_url: | |
type: string | |
description: Link to the customer resource | |
required: | |
- firstname | |
- lastname | |
CustomerEntry: | |
type: object | |
description: Entry of a collection of customers | |
x-meta: | |
className: customerEntry | |
properties: | |
firstname: | |
type: string | |
example: Susan | |
lastname: | |
type: string | |
example: Tanner | |
customer_url: | |
type: string | |
example: /shop/customer/642 | |
required: | |
- firstname | |
- lastname | |
customers: | |
type: array | |
items: | |
$ref: '#/definitions/CustomerEntry' | |
CustomerList: | |
type: object | |
description: Collection of customers | |
x-meta: | |
className: CustomerList | |
properties: | |
meta: | |
$ref: '#/definitions/Meta' | |
customers: | |
$ref: '#/definitions/customers' | |
ActionDescription: | |
type: object | |
description: Description of a possible action on the resource | |
x-meta: | |
className: ActionDescription | |
properties: | |
url: | |
type: string | |
example: /shop/orders/7959/actions/purchase | |
method: | |
type: string | |
enum: | |
- POST | |
Actions: | |
type: object | |
description: Actions that the order supports | |
example: | |
purchase: | |
url: /shop/orders/7959/actions/purchase | |
method: POST | |
x-meta: | |
className: Actions | |
properties: | |
purchase: | |
$ref: '#/definitions/ActionDescription' | |
cancel: | |
$ref: '#/definitions/ActionDescription' | |
Order: | |
type: object | |
description: Order details | |
x-meta: | |
className: Order | |
properties: | |
createdAt: | |
type: string | |
format: date | |
updatedAt: | |
type: string | |
format: date | |
state: | |
type: string | |
description: State of the order | |
enum: | |
- created | |
- ordered | |
- delivered | |
- canceled | |
customer_url: | |
type: string | |
example: /shop/customers/342 | |
actions: | |
$ref: '#/definitions/Actions' | |
items_url: | |
type: string | |
total: | |
type: number | |
description: Price of a good | |
example: '4.50' | |
x-constraint: | |
positive: true | |
required: | |
- actions | |
OrderEntry: | |
type: object | |
description: List entry of an order | |
x-meta: | |
className: OrderEntry | |
properties: | |
createdAt: | |
type: string | |
format: date | |
state: | |
type: string | |
description: State of the order | |
enum: | |
- created | |
- ordered | |
- delivered | |
- canceled | |
order_url: | |
type: string | |
example: /shop/orders/7832 | |
orders: | |
type: array | |
items: | |
$ref: '#/definitions/OrderEntry' | |
OrderList: | |
type: object | |
description: Collection of orders | |
x-meta: | |
className: OrderList | |
properties: | |
meta: | |
$ref: '#/definitions/Meta' | |
orders: | |
$ref: '#/definitions/orders' | |
Product: | |
type: object | |
description: Product description | |
example: | |
name: Wildberries | |
price: 4.99 | |
category_url: /shop/categories/Fruits | |
vendor_url: /shop/vendors/672 | |
x-meta: | |
className: Product | |
properties: | |
name: | |
type: string | |
description: Name of a product | |
example: Berries | |
price: | |
type: number | |
description: Price of a good | |
example: '4.50' | |
x-constraint: | |
positive: true | |
category: | |
type: string | |
description: Category of products e.g. Fruits | |
example: Fruits | |
vendor_url: | |
type: string | |
category_url: | |
type: string | |
vendor: | |
type: integer | |
photo_url: | |
type: string | |
required: | |
- price | |
Vendor: | |
type: object | |
description: Vendor of products | |
example: | |
name: Franks Fresh Fruits from France Ltd. | |
x-meta: | |
className: Vendor | |
properties: | |
name: | |
type: string | |
description: Name of the vendor | |
example: foo | |
products_url: | |
type: string | |
description: URL to the products of this vendor | |
vendor_url: | |
type: string | |
description: URL of the vendor | |
required: | |
- name | |
VendorEntry: | |
type: object | |
description: Listentry of a vendor | |
x-meta: | |
className: VendorEntry | |
properties: | |
name: | |
type: string | |
description: Name of the vendor | |
vendor_url: | |
type: string | |
required: | |
- name | |
vendors: | |
type: array | |
items: | |
$ref: '#/definitions/VendorEntry' | |
VendorList: | |
type: object | |
description: Collection of vendors | |
x-meta: | |
className: VendorList | |
properties: | |
meta: | |
$ref: '#/definitions/Meta' | |
vendors: | |
$ref: '#/definitions/vendors' | |
Item: | |
type: object | |
description: Item details | |
example: | |
quantity: 5 | |
price: 0.9 | |
item_url: /shop/orders/1432/items/1 | |
product_url: /shop/products/3 | |
x-meta: | |
className: Item | |
properties: | |
quantity: | |
type: number | |
example: 5 | |
price: | |
type: number | |
description: Price of a good | |
example: '4.50' | |
x-constraint: | |
positive: true | |
item_url: | |
type: string | |
product: | |
type: number | |
product_url: | |
type: string | |
order_url: | |
type: string | |
required: | |
- price | |
ItemList: | |
type: array | |
description: Collection of items | |
x-meta: | |
className: ItemList | |
items: | |
$ref: '#/definitions/Item' | |
Items: | |
type: object | |
description: Collection of items | |
x-meta: | |
className: Items | |
properties: | |
order_url: | |
type: string | |
example: /shop/orders/1432 | |
items: | |
$ref: '#/definitions/ItemList' | |
required: | |
- items | |
File: | |
type: object | |
ProductImage: | |
type: object | |
description: Image of a product | |
properties: | |
file: | |
$ref: '#/definitions/File' | |
CustomerPatch: | |
type: object | |
description: 'Any properties of the customer can be updated e.g. { "firstname": "Kai" }' | |
example: | |
firstname: Fred | |
lastname: Meyers | |
x-meta: | |
className: CustomerPatch | |
properties: | |
firstname: | |
type: string | |
example: Fred | |
lastname: | |
type: string | |
example: Meyers | |
ProductPatch: | |
type: object | |
description: Structure to patch a product. All the properties are optional. | |
example: | |
name: Wildberries | |
price: 4.99 | |
category_url: /shop/categories/Fruits | |
vendor_url: /shop/vendors/672 | |
x-meta: | |
className: ProductPatch | |
properties: | |
name: | |
type: string | |
description: Name of a product | |
example: Berries | |
price: | |
type: number | |
description: Price of a good | |
example: '4.50' | |
x-constraint: | |
positive: true | |
category: | |
type: string | |
description: Category of products e.g. Fruits | |
example: Fruits | |
vendor_url: | |
type: string | |
category_url: | |
type: string | |
vendor: | |
type: integer | |
NamePriceCategory: | |
type: object | |
properties: | |
name: | |
type: string | |
price: | |
type: number | |
category: | |
type: string | |
required: | |
- name |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment