Now that we have a REST API, let's document it using Swagger. Swagger makes it easy for other developers and tools to consume our REST API.
Complete Document
Below is the complete Swagger document for our REST API.
swagger: '2.0'
info:
version: '1.0'
title: 'Item Service'
description: 'Item Service API'
host: www.example.com
basePath: /
schemes:
- http
definitions:
item:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
maxLength: 255
description:
type: string
maxLength: 65535
price:
type: number
format: float
minimum: 0
maximum: 999999999.99
items:
type: array
items:
$ref: "#/definitions/item"
paths:
/items:
get:
summary: Returns a list of items.
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/items'
post:
summary: Create a new item.
parameters:
- name: "body"
in: "body"
description: "New item object."
required: true
schema:
$ref: '#/definitions/item'
responses:
201:
description: Created
headers:
Location:
type: string
description: URL of the created item.
/items/{id}:
parameters:
- in: path
name: id
description: The id of the item to be acted upon.
type: integer
format: int64
required: true
get:
summary: Returns the item corresponding to the id.
produces:
- application/json
responses:
200:
description: OK
schema:
$ref: '#/definitions/item'
404:
description: Not Found
put:
summary: Update an existing item.
parameters:
- name: "body"
in: "body"
description: "New item object."
required: true
schema:
$ref: '#/definitions/item'
responses:
204:
description: No Content
404:
description: Not Found
delete:
summary: Delete an exisiting item.
responses:
204:
description: "No Content"
Definitions
In this section we can define what the structure of the input and output bodies are. We have defined two structures: item and items. Item corresponds to a single item, and items corresponds to an array of items.
definitions:
item:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
maxLength: 255
description:
type: string
maxLength: 65535
price:
type: number
format: float
minimum: 0
maximum: 999999999.99
items:
type: array
items:
$ref: "#/definitions/item"
Paths
We will define each of the paths for our service. A path consists of fixed and variable pieces.
- "items" is a fixed part of the path.
- "{id}" is a parameter in the path.
- We have defined the "item" parameter to be of type "integer" that is capable of holding numbers that correspond to the "int64" format.
- We have specified that this parameter is required.
/items/{id}:
parameters:
- in: path
name: id
description: The id of the item to be acted upon.
type: integer
format: int64
required: true
Methods
We need to document each of the HTTP methods for our service.
- This is a definition for the GET method.
- We have specified that the method returns content of type "application/json".
- The possible HTTP responses are 200 and 404.
- A 200 response returns a JSON document that corresponds to the item type that we defined.
get:
summary: Returns the item corresponding to the id.
produces:
- application/json
responses:
200:
description: OK
schema:
$ref: '#/definitions/item'
404:
description: Not Found
Useful Links
Below are some links that I found helpful when creating this post:
- Data Types
https://swagger.io/docs/specification/data-models/data-types/
- Chapter 11 Data Types
https://dev.mysql.com/doc/refman/8.0/en/data-types.html
No comments:
Post a Comment