openapi: 3.0.0
info:
  title: Suggestion
  version: 2.0.0
  description: >
    A **Suggestion** is a recommendation that 4HSE produces for the user to
    review. Each suggestion

    has a `type`, which determines how it is interpreted and what applying it
    does, and a `data`

    payload describing what is being proposed.


    A suggestion is linked to the entities it concerns, so the same
    recommendation can point at a

    person, an office, or another resource.


    Use this API to:

    - List the open suggestions

    - Apply one or more suggestions (`exec`) — this performs the change the
    suggestion proposes

    - Dismiss a suggestion (`delete`)


    Dismissing is per user and does not erase the suggestion: it is moved to the
    discarded list of

    the user who dismissed it, and stays visible to the others.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/suggestion/index:
    post:
      summary: index
      operationId: indexSuggestion
      tags:
        - Suggestions
      description: |
        Returns a paginated and filterable list of suggestions.  
        Use POST to allow complex filters via JSON payload.
      requestBody:
        description: Parameters for searching suggestions
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SuggestionIndexParams"
            example:
              filter:
                type: improvement
              per-page: 10
              page: 1
              sort: type
      responses:
        "200":
          description: List of suggestions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Suggestion"
              example:
                suggestion_id: sug-1
                type: improvement
                data: '{"message":"Add a new feature"}'
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/suggestion/view/{id}:
    get:
      summary: view
      operationId: viewSuggestion
      tags:
        - Suggestions
      description: |
        Retrieve a suggestion by its unique ID.
      parameters:
        - name: id
          in: path
          description: ID of the suggestion to retrieve
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Suggestion found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Suggestion"
              example:
                suggestion_id: sug-1
                type: improvement
                data: '{"message":"Add a new feature"}'
        "404":
          description: Suggestion not found
components:
  schemas:
    Suggestion:
      type: object
      properties:
        suggestion_id:
          type: string
          description: The unique identifier for the suggestion.
        type:
          type: string
          maxLength: 50
          enum:
            - ACTION_SUBSCRIPTION
            - CERTIFICATE_ACTION
          description: The type of the suggestion.
        data:
          type: string
          format: json
          description: Additional data related to the suggestion, in JSON format.
    SuggestionIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/Suggestion"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order (e.g.
            -type).
          enum:
            - type
      example:
        filter:
          type: ACTION_SUBSCRIPTION
        per-page: 100
        page: 1
        sort: type
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
