components:
    schemas:
        TicketComment:
            type: object
            properties:
                id:
                    type: integer
        TicketSimple:
            type: object
            properties:
                id:
                    type: integer
        Motive:
            type: object
            properties:
                id:
                    type: integer
                label:
                    type: object
                    additionalProperties:
                        type: string
                    example:
                        fr: Retard de livraison
                active:
                    type: boolean
        MotiveById:
            type: object
            properties:
                id:
                    type: integer
                type:
                    type: string
                    enum:
                        - ticket_motive
            required:
                - id
                - type

paths:
    /1.0/ticket/ticket/{id}:
        get:
            tags:
                - ticket
            summary: Details of a ticket
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            responses:
                200:
                    description: "OK"
    /1.0/ticket/ticket/list:
        get:
            tags:
                - ticket
            summary: List of tickets
            parameters:
                - name: byTicketId
                  in: query
                  description: >
                    The id of the ticket.

                    When the id of the ticket is set, the other parameters are ignored.
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: integer
                      minimum: 0
                - name: byPerson
                  in: query
                  description: the id of the person
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: integer
                          format: integer
                          minimum: 1
                - name: byCurrentState
                  in: query
                  description: the current state of the ticket
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: string
                          enum:
                              - open
                              - closed
                - name: byCurrentStateEmergency
                  in: query
                  description: the current state emergency of the ticket
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: string
                          enum:
                              - yes
                              - no
                - name: byMotives
                  in: query
                  description: the motives of the ticket
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: integer
                          format: integer
                          minimum: 1
                - name: byCreatedBefore
                  in: query
                  description: "Filter by the creation date for the ticket: only tickets created before the given date."
                  required: false
                  schema:
                      type: string
                      format: date-time
                - name: byCreatedAfter
                  in: query
                  description: "Filter by the creation date for the ticket: only tickets crated after the given date."
                  required: false
                  schema:
                      type: string
                      format: date-time
                - name: byResponseTimeExceeded
                  in: query
                  allowEmptyValue: true
                  description: |
                      Filter tickets that are not closed and have a response time exceeded (configuration parameter).

                      The value of this parameter is ignored.

                      **Warning**: This silently remove the filters "byCurrentState" and "byCreatedBefore".
                  schema:
                      type: string
                - name: byAddressee
                  in: query
                  description: "The id of the addressee to search for. The search is also performed against user groups: the api endpoint filter for ticket assigned to the groups of the user given as parameter."
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: integer
                          format: integer
                          minimum: 1
                - name: byAddresseeToMe
                  in: query
                  description: filter tickets assigned to the current authenticated users
                  required: false
                  allowEmptyValue: true
                  schema:
                      type: string
                - name: byAddresseeGroup
                  in: query
                  description: the id of the addressee users group to search for.
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: integer
                          format: integer
                          minimum: 1
                - name: byCreator
                  in: query
                  description: The id of the creator to search for.
                  required: false
                  style: form
                  explode: false
                  schema:
                      type: array
                      items:
                          type: integer
                          format: integer
                          minimum: 1
            responses:
                200:
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    - $ref: '#components/schemas/Collection'
                                    - type: object
                                      properties:
                                          results:
                                              type: array
                                              items:
                                                  $ref: '#components/schemas/TicketSimple'


    /1.0/ticket/motive.json:
        get:
            tags:
                - ticket
            summary: A list of available ticket's motive
            responses:
                200:
                    description: "OK"

    /1.0/ticket/{id}/motive/set:
        post:
            tags:
                - ticket
            summary: Replace the existing ticket's motive by a new one
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                motive:
                                    $ref: "#/components/schemas/MotiveById"
            responses:
                201:
                    description: "ACCEPTED"
                422:
                    description: "UNPROCESSABLE ENTITY"

    /1.0/ticket/{id}/comment/add:
        post:
            tags:
                - ticket
            summary: Add a comment to an existing ticket
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                content:
                                    type: string
            responses:
                201:
                    description: "ACCEPTED"
                422:
                    description: "UNPROCESSABLE ENTITY"
    /1.0/ticket/comment/{id}/edit:
        post:
            tags:
                - ticket
            summary: Edit the comment' content
            parameters:
                -  name: id
                   in: path
                   required: true
                   description: The comment's id
                   schema:
                       type: integer
                       format: integer
                       minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                content:
                                    type: string
            responses:
                200:
                    description: "OK"
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TicketComment'
                403:
                    description: "Unauthorized"

    /1.0/ticket/comment/{id}/delete:
        post:
            tags:
                - ticket
            summary: Soft-delete a comment within a ticket
            description: |
                This will soft delete a comment within a ticket.

                Only the author of the comment is allowed to edit the comment.

                If a comment is deleted, it can be restored by using the "restore" call.

                The method is idempotent: it will have no effect on an already deleted comment.
            parameters:
                -  name: id
                   in: path
                   required: true
                   description: The comment's id
                   schema:
                       type: integer
                       format: integer
                       minimum: 1
            responses:
                200:
                    description: "OK"
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TicketComment'
                403:
                    description: "Unauthorized"

    /1.0/ticket/comment/{id}/restore:
        post:
            tags:
                - ticket
            summary: Restore a comment within a ticket
            description: |
                This will restore a comment of a ticket.

                Only the author of the comment is allowed to restore the comment.

                If the comment is not deleted, this method has no effect.

            parameters:
                -  name: id
                   in: path
                   required: true
                   description: The comment's id
                   schema:
                       type: integer
                       format: integer
                       minimum: 1
            responses:
                200:
                    description: "OK"
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TicketComment'
                403:
                    description: "Unauthorized"

    /1.0/ticket/{id}/persons/set:
        post:
            tags:
                - ticket
            summary: Associate a person with the ticket
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                persons:
                                    type: array
                                    items:
                                        $ref: '#/components/schemas/PersonById'
            responses:
                200:
                    description: "OK"
    /1.0/ticket/{id}/addressees/set:
        post:
            tags:
                - ticket
            summary: Set the addresses for an existing ticket (will replace all the existing addresses)
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                addressees:
                                    type: array
                                    items:
                                        oneOf:
                                            -   $ref: '#/components/schemas/UserGroupById'
                                            -   $ref: '#/components/schemas/UserById'


            responses:
                201:
                    description: "ACCEPTED"
                422:
                    description: "UNPROCESSABLE ENTITY"

    /1.0/ticket/{id}/addressee/add:
        post:
            tags:
                - ticket
            summary: Add an addressee to a ticket, without removing existing ones.
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                addressee:
                                    oneOf:
                                        -   $ref: '#/components/schemas/UserGroupById'
                                        -   $ref: '#/components/schemas/UserById'


            responses:
                201:
                    description: "ACCEPTED"
                422:
                    description: "UNPROCESSABLE ENTITY"

    /1.0/ticket/ticket/{id}/close:
        post:
            tags:
                - ticket
            summary: Close a ticket
            description: |
                Close an existing ticket.

                If the ticket is already close, no action will be performed on this ticket: his state will remains unchanged, and the
                ticket will be returned.
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            responses:
                200:
                    description: "OK"
                401:
                    description: "UNAUTHORIZED"
    /1.0/ticket/ticket/{id}/open:
        post:
            tags:
                - ticket
            summary: Open a ticket
            description: |
                Re-open an existing ticket.

                If the ticket is already opened, no action will be performed on this ticket: his state will remains unchanged, and the
                ticket will be returned.
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            responses:
                200:
                    description: "OK"
                401:
                    description: "UNAUTHORIZED"
    /1.0/ticket/ticket/{id}/emergency/{emergency}:
        post:
            tags:
                - ticket
            summary: Set a ticket as emergency
            description: |
                Re-open an existing ticket.

                If the ticket is already opened, no action will be performed on this ticket: his state will remains unchanged, and the
                ticket will be returned.
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
                -   name: emergency
                    in: path
                    required: true
                    description: the new state of emergency
                    schema:
                        type: string
                        enum:
                            - yes
                            - no
            responses:
                200:
                    description: "OK"
                401:
                    description: "UNAUTHORIZED"

    /1.0/ticket/ticket/{id}/set-caller:
        post:
            tags:
                - ticket
            summary: Set a caller for this ticket
            description: |
                Set a caller to the ticket.

                To remove the caller, set the caller field to null
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                caller:
                                    nullable: true
                                    oneOf:
                                        -   $ref: '#/components/schemas/PersonById'
                                        -   $ref: '#/components/schemas/ThirdPartyById'
                        examples:
                            add_user:
                                value:
                                    caller:
                                        type: person
                                        id: 8
                                summary: Set the person with id 8
                            add_third_party:
                                value:
                                    caller:
                                        type: thirdparty
                                        id: 10
                                summary: Set the third party with id 10
                            remove:
                                value:
                                    caller: null
                                summary: Remove the caller (set the caller to null)

            responses:
                200:
                    description: "OK"
                401:
                    description: "UNAUTHORIZED"
    /1.0/ticket/ticket/{id}/suggest-person:
        get:
            tags:
                - ticket
            summary: Get a list of person suggested for the given ticket
            parameters:
                -   name: id
                    in: path
                    required: true
                    description: The ticket id
                    schema:
                        type: integer
                        format: integer
                        minimum: 1
            responses:
                401:
                    description: "UNAUTHORIZED"
                200:
                    description: "OK"
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Person'