components:
    schemas:
        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: 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
            responses:
                200:
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    - $ref: '#components/schemas/Collection'
                                    - type: object
                                      properties:
                                          results:
                                              type: array
                                              items:
                                                  $ref: '#component/schema/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/{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'