swagger: "2.0"
info:
  description: >-
    REST API for the User Management Service
  version: "1"
  title: "User Management"
  termsOfService: "Experimental, no SLA"
  contact:
    email: "development@bbgo.org"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
# host: "localhost"
basePath: "/user-service/v1"
tags:
- name: User
  description: "User"

- name: Token
  description: "Token"

schemes:
- "https"
- "http"
paths:
  /users:
    post:
      tags:
      - User
      summary: "an operation to register a new user"
      description: >-
        Registers a new user
      operationId: "registerUser"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: payload
        in: body
        description: >-
          Data for the user to be registered
        schema:
          $ref: "./Data.yaml"
        required: true
      responses:
        201:
          description: Created
          headers:
            Location:
              description: URI of the registered resource
              type: string
              #format: uri
            ETag:
              description: >-
                Fingerprint of the created resource
              type: string
          schema:
            $ref: "./User.yaml"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        500:
          $ref: "./responses.yaml#/500"

    get:
      tags:
      - User
      summary: Get all users
      description: >-
        Get all users
      operationId: "getUsers"
      produces:
      - "application/json"
      parameters:
      - $ref: "./parameters.yaml#/filter"
      - $ref: "./parameters.yaml#/top"
      - $ref: "./parameters.yaml#/skip"
      - $ref: "./parameters.yaml#/search"
      responses:
        200:
          description: OK
          schema:
            $ref: "./Users.yaml"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        404:
          $ref: "./responses.yaml#/404"
        500:
          $ref: "./responses.yaml#/500"
      security:
      - tokenAuth: [ADMIN, USER]

  /users/{id}:
    get:
      tags:
      - User
      summary: "Retrieve a user by ID"
      description: >-
        Returns user
      operationId: "getUser"
      produces:
      - "application/json"
      parameters:
      - in: path
        name: "id"
        description: "User ID"
        type: string
        required: true
      responses:
        200:
          description: OK
          headers:
            ETag:
              description: >-
                Fingerprint of the user object retrieved
              type: string
          schema:
            $ref: "./User.yaml"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        404:
          $ref: "./responses.yaml#/404"
        500:
          $ref: "./responses.yaml#/500"
      security:
      - tokenAuth: [ADMIN, USER]

    delete:
      tags:
      - User
      summary: Deletes a user
      description: >-
        Deletes a user
      operationId: deleteUser
      parameters:
      - name: id
        in: path
        description: ID of a user to delete
        required: true
        type: "string"
      responses:
        204:
          $ref: "./responses.yaml#/204"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        404:
          $ref: "./responses.yaml#/404"
        500:
          $ref: "./responses.yaml#/500"
      security:
      - tokenAuth: [ADMIN, USER]

  /users/{id}/data:
    put:
      tags:
      - User
      summary: Update an existing user data
      description: >-
        Updates data for an existing user
      operationId: updateData
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: ID of the user to update
        type: string
        required: true
      - in: body
        name: payload
        description: User data to be updated
        required: true
        schema:
          $ref: "./Data.yaml"
      - $ref: "./parameters.yaml#/ifmatch"
      responses:
        200:
          description: OK
          headers:
            ETag:
              description: "Fingerprint of the user object updated"
              type: string
          schema:
            $ref: "./User.yaml"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        404:
          $ref: "./responses.yaml#/404"
        412:
          $ref: "./responses.yaml#/412"
        500:
          $ref: "./responses.yaml#/500"
      security:
      - tokenAuth: [ADMIN, USER]

  /users/{id}/roles:
    put:
      tags:
      - User
      summary: Update roles for an existing user
      description: >-
        Updates roles for an existing user
      operationId: updateRoles
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: path
        name: id
        description: ID of the user to update
        type: string
        required: true
      - in: body
        name: payload
        description: User roles to be updated
        required: true
        schema:
          $ref: "./Roles.yaml"
      - $ref: "./parameters.yaml#/ifmatch"
      responses:
        200:
          description: OK
          headers:
            ETag:
              description: "Fingerprint of the user object updated"
              type: string
          schema:
            $ref: "./User.yaml"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        404:
          $ref: "./responses.yaml#/404"
        412:
          $ref: "./responses.yaml#/412"
        500:
          $ref: "./responses.yaml#/500"
      security:
      - tokenAuth: [ADMIN, USER]

  /token:
    post:
      tags:
      - Token
      summary: Issues a token for an authenticated user
      description: >-
        Issues a token for an authenticated user
      operationId: issueToken
      produces:
      - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: "./AccessToken.yaml"
        400:
          $ref: "./responses.yaml#/400"
        401:
          $ref: "./responses.yaml#/401"
        403:
          $ref: "./responses.yaml#/403"
        404:
          $ref: "./responses.yaml#/404"
        412:
          $ref: "./responses.yaml#/412"
        500:
          $ref: "./responses.yaml#/500"
      security:
      - basicAuth: []

securityDefinitions:
  basicAuth:
    type: basic
  tokenAuth:
    type: apiKey
    in: header
    name: Authorization