Swagger definitions.

Back to Documentation main page

In a Swagger based API, the HTTP server responses and all it related data, strictly follow a contract which defines it formats.

The Swagger definition specifications defines:

  1. How every Data Entities behave.
  2. Request definitions
  1. Response definitions

Please consider the following routes specification file: ./src/lib/api/swagger/definitions/DemoUser.definition.yaml

definitions:
  # Object used when listing one item
  DemoUser_response:
    properties:
      code:
        type: "integer"
        format: "int32"
        example: 200
      message:
        type: "string"
        example: "successful operation"
      data:
        type: "object"
        $ref: "#/definitions/DemoUser"
  # Object used when listing multiple items
  DemoUser_collection:
    properties:
      code:
        type: "integer"
        format: "int32"
        example: 200
      message:
        type: "string"
        example: "successful operation"
      data:
        type: "array"
        items:
          $ref: "#/definitions/DemoUser"
  # Object used when creating an item
  DemoUser_response_created:
    properties:
      code:
        type: "integer"
        format: "int32"
        example: 201
      message:
        type: "string"
        example: "Created"
      id:
        type: "string"
        example: 5c0fb100ec2339ed5bea6303
      data:
        $ref: "#/definitions/DemoUser"
  # Object used when creating an item
  DemoUser_response_updated:
    properties:
      code:
        type: "integer"
        format: "int32"
        example: 200
      message:
        type: "string"
        example: "successful operation"
      id:
        type: "string"
        example: 5c0fb100ec2339ed5bea6303
      data:
        $ref: "#/definitions/DemoUser"
  DemoUser:
    properties:
      _id:
        type: "string"
      email:
        type: "string"
      first_name:
        type: "string"
      last_name:
        type: "string"
  DemoUser_create:
    required: ["email","first_name","last_name"]
    properties:
      email:
        type: "string"
      first_name:
        type: "string"
      last_name:
        type: "string"