Item Service - Using Swagger to Document the REST API

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.

1. "items" is a fixed part of the path.
2. "{id}" is a parameter in the path.
3. We have defined the "item" parameter to be of type "integer" that is capable of holding numbers that correspond to the "int64" format.
4. 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.

1. This is a definition for the GET method.
2.  We have specified that the method returns content of type "application/json".
3. The possible HTTP responses are 200 and 404.
4. 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:

1. Data Types
   https://swagger.io/docs/specification/data-models/data-types/
2. Chapter 11 Data Types
   https://dev.mysql.com/doc/refman/8.0/en/data-types.html