swagger: "2.0"
info:
  version: "1.1.0"
  title: User Manager
  description: >
    This is a sample API for managing a database of users.  User accounts can be created, deleted, edited, and retrieved.
    Users can also log-in, which will create a session cookie. Logging out will delete the cookie.

host: localhost:3000
consumes:
  - application/json
produces:
  - application/json

definitions:
  # A simple username/password combo for logging in
  login:
    required: [username, password]
    properties:
      username:
        type: string
        minLength: 1
      password:
        type: string
        minLength: 1

  # The user schema is defined in the "user.yaml" file.
  # Swagger-Server will automatically convert the user.yaml
  # file to JSON format
  user:
    # this is not a complete swagger spec.  it's just a json schema (in yaml format)
# that's referenced by the "users.yaml" spec using "$ref: http://localhost:3000/users.json"
#
# note that swagger-server will automatically convert the yaml to json when serving
# the file.  if you prefer to author the file in json instead of yaml, then that's ok too.

description: a registered user
required: [username, password, name]
properties:
  username:
    type: string
    minlength: 4
    maxlength: 20
    pattern: "^\\w+$"   # only allows alphanumeric characters
    description: username must be unique
  password:
    type: string
    minlength: 4
    description: a super-secure, four-character password :)
  name:
    type: object
    description: the user's real name
    required: [firstname]
    properties:
      firstname:
        type: string
        minlength: 1
      lastname:
        type: string
  email:
    type: string
  telephone:
    type: integer
    minimum: 1000000000
  lastlogindate:
    type: string
    format: date-time
    description: when the user last logged in (set by the server)
    readonly: true
example:
  username: jdoe
  name:
    firstname: john
    lastname: doe
  email: john.doe@abc.com
  telephone: 5551234567
  lastlogindate: 2015-05-11t14-00-32z


# NOTE: This does NOT set global parameters for all operations.
# It just defines parameter templates that can be referenced by operations (i.e. it saves typing)
parameters:
  sessionCookie: &sessionCookie
    name: Cookie
    in: header
    required: true
    type: string
    description: The session cookie

  username: &username
    name: username
    in: path
    required: true
    type: string
    description: This is the {username} path parameter

  userData: &userData
    name: body
    in: body
    required: true
    schema:
      $ref: user
    description: The user data for create/update operations


paths:
  /users:
    get:
      summary: Returns all users in the database.
      description: Only the "admin" user can access this.
      responses:
        200:
          description: Returns the list of users
          schema:
            type: array
            items:
              $ref: user
        401:
          description: Hey! You're not the "admin" user!

    post:
      summary: Creates a new user
      description: Only the "admin" user can create users.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: user
          description: The user account to create
      responses:
        201:
          description: New user was created successfully
          schema:
            $ref: user
          headers:
            Location:
              type: string
              description: The Server returns the URL of the new user
        400:
          description: Bad JSON formatting in the request


  /users/{username}:
    get:
      summary: Retrieves a user
      description: >
        users can only retrieve their own account, not other users'. Except for the "admin" user, who can retrieve anyone.
      parameters:
        - *username
        - *sessionCookie
      responses:
        200:
          description: Returns the user's data
          schema:
            $ref: user
        401:
          description: You tried to retrieve someone else's account, and you're not the "admin" user.
        404:
          description: The {username} was not found

    post:
      summary: Edits a user
      description: >
        Users can only edit their own account, not other users'.  Except for the "admin" user, who can edit anyone.
      parameters:
        - *username
        - *userData
        - *sessionCookie
      responses:
        200:
          description: User data was saved successfully
          schema:
            $ref: user
        400:
          description: Bad JSON formatting in the request
        401:
          description: You tried to edit someone else's account, and you're not the "admin" user.
        404:
          description: The {username} was not found

    delete:
      summary: Deletes a user
      description: >
        Users can only delete their own account, not other users'.  Except for the "admin" user, who can delete anyone.
      parameters:
        - *username
        - *sessionCookie
      responses:
        204:
          description: User account was deleted
        401:
          description: You tried to edit someone else's account, and you're not the "admin" user.
        404:
          description: The {username} was not found


  /users/login:
    post:
      summary: Logs in
      description: |
        Try logging in with username "jdoe" and password "jdoe".
        Then try logging in with username "admin" and password "admin".
      parameters:
        - name: body
          in: body
          required: true
          description: The login credentials
          schema:
            $ref: login
      responses:
        200:
          description: Login was successful
          schema:
            $ref: user
          headers:
            Set-Cookie:
              type: string
              description: The session cookie
              default: demo-session-id=123456789012345678901234567890


  /users/{username}/logout:
    post:
      summary: Logs out the given user
      description: >
        Users can only log themselves out, not other users. Except the "admin" user, who can log-out anyone.
      parameters:
        - *username
        - *sessionCookie
      responses:
        204:
          description: Logout was successful
          headers:
            Set-Cookie:
              type: string
              description: Deletes the session cookie (by making expire in the past)
              default: demo-session-id=deleted; Expires=Thu, 01-Jan-1970 00:00:01 GMT; Path=/
        401:
          description: You tried to log someone else out, and you're not the "admin" user.
        404:
          description: The {username} was not found