swagger.yml

swagger: '2.0'
info:
  version: 1.0.0
  title: Typescript Node Api
basePath: "/api"
tags:
  - name: Product Categories
consumes:
- application/json
produces:
- application/json
paths:
  /v1/product-categories:
    get:
      summary: Retrieve a list of product categories
      tags:
        - Product Categories
      parameters:
        - name: offset
          in: query
          description: The first result to return
          type: integer
          default: 0
        - name: limit
          in: query
          description: The amount of results to return
          type: integer
          default : 25
      responses:
        200:
          description: OK
          headers:
            x-request-id:
              description: The request identifier
              type: string
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/definitions/ProductCategoryResource'
              total:
                type: integer
                description: The total amount of records found
              offset:
                type: integer
                description: The first result to return
              limit:
                type: integer
                description: The amount of records to return
        400:
          $ref: '#/components/responses/BadRequest'
    post:
      summary: Create a new product category
      tags:
        - Product Categories
      parameters:
        - in: body
          name: body
          required: true
          schema:
            "$ref": "#/definitions/ProductCategoryResource"
      responses:
        201:
          description: Created
          headers:
            x-request-id:
              description: The request identifier
              type: string
          schema:
            $ref: '#/definitions/ProductCategoryResource'
        400:
          $ref: '#/components/responses/BadRequest'
        409:
          $ref: '#/components/responses/Conflict'
  /v1/product-categories/{id}:
    get:
      summary: Retrieve a single product category
      tags:
        - Product Categories
      parameters:
        - name: id
          in: path
          description: The resource identifier
          required: true
          type: string
      responses:
        200:
          description: OK
          headers:
            x-request-id:
              description: The request identifier
              type: string
          schema:
            type: object
            $ref: '#/definitions/ProductCategoryResource'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
definitions:
  ProductCategoryResource:
    properties:
      id:
        type: string
        example: 59de80da99e5f90280ee3e24
        readOnly: true
      code:
        type: string
        example: MOBPHO
      name:
        type: string
        example: Mobile Phones
      description:
        type: string
        example: Everything concerning mobile phones
    required:
      - code
      - name
  ValidationResultItem:
    properties:
      message:
        type: string
        example: field is required
      path:
        type: array
        example:
          - body
          - field
        items:
          type: string
components:
  responses:
    BadRequest:
      description: Bad Request
      allOf:
        - $ref: '#/components/schemas/StatusError'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/definitions/ValidationResultItem'
      examples:
        application/json:
          statusCode: 400
          error: Bad Request
          message: Bad Request
    Conflict:
      description: Unauthorized
      schema:
        $ref: '#/components/schemas/StatusError'
      examples:
        application/json:
          statusCode: 409
          error: Conflict
          message: The 'Resource' already exists (code:'XX')
    NotFound:
      description: Not Found
      schema:
        $ref: '#/components/schemas/StatusError'
      examples:
        application/json:
          statusCode: 404
          error: Not Found
          message: The 'Resource' is not found
    Unauthorized:
      description: Unauthorized
      schema:
        $ref: '#/components/schemas/StatusError'
    Forbidden:
      description: Forbidden
      schema:
        $ref: '#/components/schemas/StatusError'
  schemas:
    StatusError:
      type: object
      properties:
        statusCode:
          type: integer
        error:
          type: string
        message:
          type: string
      required:
        - statusCode
        - error