@inspire-platform/sails-hook-auth/swagger.yaml

Passport-based User Authentication system for sails.js applications.

swagger: '2.0'
info:
  title: sails-hook-auth
consumes:
  - application/json

tags:
- name: auth
  description: Authentication
- name: user
  description: User collection

paths:

  /auth/local:

    post:
      operationId: authLocal
      tags: [auth]
      summary: Authenticate locally guys
      description: Authenticate locally
      security: []
      parameters:
        - name: body
          in: body
          schema:
            $ref: '#/definitions/AuthLocal'
      responses:
        '200':
          description: Authenticated User
          schema:
            $ref: '#/definitions/User'

  /auth/logout:

    post:
      operationId: authLogout
      tags: [auth]
      summary: Session logout
      description: Destroys session for current user
      security: []
      responses:
        '200':
          $ref: "./node_modules/@inspire-platform/sails-hook-swagger/swagger.json#/responses/Ok200"

  /auth/accessPolicy:

    get:
      operationId: authAccessPolicy
      tags: [auth]
      summary: Returns user access policy.
      description: Returns access policy for currently authenticated user.
      security: []
      responses:
        '200':
          description: Model access policy.
          schema:
            type: object

  /user:

    get:
      operationId: findUsers
      tags: [user]
      summary: Get Users
      description: Returns a collection of Users
      parameters:
        - $ref: '#/parameters/Limit'
        - $ref: '#/parameters/Skip'
      responses:
        '200':
          description: A collection of User objects foofoofoo
          schema:
            type: array
            items:
              $ref: '#/definitions/UserPopulated'

    post:
      operationId: createUser
      tags: [user]
      summary: Create a User
      description: Adds a new User to the collection.
      parameters:
        - name: body
          in: body
          schema:
            $ref: '#/definitions/UserNew'
      responses:
        '200':
          description: User created
          schema:
            # TODO this does not populate due to custom controller
            $ref: '#/definitions/User'

  '/user/{id}':

    get:
      operationId: findUserById
      tags: [user]
      summary: Gets one User
      description: Returns a single User by id.
      parameters:
        - name: id
          in: path
          required: true
          description: The user's ID
          type: string
          format: uuid
      responses:
        '200':
          description: A User
          schema:
            $ref: '#/definitions/UserPopulated'
        '404':
          $ref: '#/responses/ErrorUser404'

    patch:
      operationId: updateUserById
      tags: [user]
      summary: Update a User
      description: Updates a single user.
      parameters:
        - name: id
          in: path
          required: true
          description: The user's ID
          type: string
          format: uuid
        - name: body
          in: body
          schema:
            $ref: '#/definitions/UserMod'
      responses:
        '200':
          description: Updated the User
          schema:
            # TODO this does not populate due to custom controller
            $ref: '#/definitions/User'
        '404':
          $ref: '#/responses/ErrorUser404'

    delete:
      operationId: destroyUserById
      tags: [user]
      summary: Delete a User
      description: Deletes a single user.
      parameters:
        - name: id
          in: path
          required: true
          description: The user's ID
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted the User
          schema:
            $ref: '#/definitions/UserPopulated'
        '404':
          $ref: '#/responses/ErrorUser404'

#
# Definitions
#

definitions:

  #
  # Auth
  #

  AuthLocal:
    title: Auth Local
    description: Authenticate locally with a username and password.
    required:
      - identifier
      - password
    properties:
      identifier:
        type: string
        description: Username or e-mail address
        example: admin@example.com
      password:
        type: string
        format: password
        example: admin1234

  #
  # User
  #

  UserNew:
    title: New User
    required:
      - username
      - email
      - password
    properties:
      username:
        type: string
        example: admin
      email:
        type: string
        format: email
        example: admin@example.com
      firstName:
        type: string
        example: Jim
      middleName:
        type: string
        example: Bob
      lastName:
        type: string
        example: Robertson
      active:
        type: boolean
        example: true
      dashboardState:
        type: object
      password:
        type: string
        format: password
        example: admin1234

  UserMod:
    title: Modify User
    description: User properties to modify.
    properties:
      email:
        type: string
        format: email
        example: sales@example.com
      firstName:
        type: string
        example: Billy
      middleName:
        type: string
        example: Joe
      lastName:
        type: string
        example: Williams
      active:
        type: boolean
        example: true
      dashboardState:
        type: object
      password:
        type: string
        example: sales5678

  User:
    allOf:
      - $ref: "./node_modules/@inspire-platform/sails-hook-swagger/swagger.json#/definitions/Item"
      - title: User Item
      - properties:
          username:
            type: string
            example: admin
          email:
            type: string
            format: email
            example: admin@example.com
          firstName:
            type: string
            example: Jim
          middleName:
            type: string
            example: Bob
          lastName:
            type: string
            example: Robertson
          active:
            type: boolean
            example: true
          dashboardState:
            type: object
          lastLogin:
            type: string
            format: 'date-time'
            example: '2017-06-14T14:13:53.949Z'

  UserPopulated:
    allOf:
      - $ref: '#/definitions/User'
      -
        type: object
        title: User Item Populated

  #
  # Response
  #

  Success:
    $ref: "./node_modules/@inspire-platform/sails-hook-swagger/swagger.json#/definitions/Success"

  Error:
    $ref: "./node_modules/@inspire-platform/sails-hook-swagger/swagger.json#/definitions/Error"

#
# Parameters
#

parameters:

  Limit:
    name: limit
    in: query
    description: Max number of items to return.
    type: integer
    default: 0

  Skip:
    name: skip
    in: query
    description: Number of items to skip.
    type: integer
    default: 0

#
# Responses
#

responses:

  #
  # Error
  #

  ErrorUser404:
    description: User not found
    schema:
      $ref: "./node_modules/@inspire-platform/sails-hook-swagger/swagger.json#/definitions/Error"