openapi: 3.0.0
info:
  version: 0.21.0
  title: RecycleMap API
  contact:
    name: API Support
    url: https://geosemantica.ru
    email: info@geosemantica.ru
servers:
  - description: 'recyclemap.ru'
    url: 'https://recyclemap.ru'
tags:
  - name: admin
    description: Private access for administrator
  - name: auth
    description: User registration and authorization
  - name: bulk
    description: Bulk operations
  - name: comments
    description: Operations with comments
  - name: delete
    description: Delete operations
  - name: ecoadvices
    description: Operations with ecoadvices
  - name: favorites
    description: Operations with favorites
  - name: fixes
    description: Operations with fixes moderation
  - name: fractions
    description: Operations with fractions
  - name: get
    description: Get operations
  - name: headers
    description: Operations with header buttons
  - name: moderator
    description: Private access for moderator
  - name: operators
    description: Operations with point operators
  - name: patch
    description: Patch operations
  - name: photos
    description: Operations with photos
  - name: points
    description: Operations with points
  - name: private
    description: Private access for authorized user
  - name: public
    description: Public access without authorization
  - name: ratings
    description: Operations with ratings
  - name: search
    description: Operations with search
  - name: subscriptions
    description: Operations with subscription
  - name: tiles
    description: Operations with tiles
  - name: users
    description: Operations with users


paths:
  /public/points:
    $ref: './paths/PublicPoints.yaml'

  /public/points/{pointId}:
    $ref: './paths/PublicPointsId.yaml'

  /private/points:
    get:
      tags:
        - private
        - points
        - get
      security:
        - BearerAuth: [ ]
      summary: Get list of points with short description
      operationId: getPrivatePoints
      parameters:
        - $ref: './parameters/BBox.yaml'
        - $ref: './parameters/QuerySize.yaml'
        - $ref: './parameters/Fractions.yaml'
        - $ref: './parameters/RestrictedPoint.yaml'
        - $ref: './parameters/BusinessHours.yaml'
        - $ref: './parameters/Offset.yaml'
        - $ref: '#/components/parameters/MyComments'
        - $ref: '#/components/parameters/MyPoints'
        - $ref: '#/components/parameters/MyEdits'
        - $ref: '#/components/parameters/MyFavorites'
      responses:
        200:
          description: A list of points
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalResults:
                            type: number
                          points:
                            type: array
                            items:
                              $ref: '#/components/schemas/PointShortAuthUser'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'
    post:
      tags:
        - private
        - points
        - post
      summary: Add new Point
      operationId: postPrivatePoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/PointEditFields'
                - required:
                  - title
                  - address
                  - geom
                  - fractions
                  - pointDescription
                  - schedule
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /private/points/{pointId}:
    get:
      tags:
        - private
        - points
        - get
      security:
        - BearerAuth: [ ]
      summary: Get full information about Point with User related data
      operationId: getPrivatePointsById
      parameters:
        - $ref: './parameters/PointId.yaml'
      responses:
        200:
          description: Full Point information with User related data
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PointAuthUser'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'
    patch:
      tags:
        - private
        - points
        - patch
      security:
        - BearerAuth: [ ]
      summary: Edit information about Point
      operationId: patchPrivatePointsById
      parameters:
        - $ref: './parameters/PointId.yaml'
      requestBody:
        required: true
        description: |
          use values for clearing fields:
          - addressDescription, scheduleDescription: "\_REMOVE\_"
          - validDates, photoset: [ ]
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/PointEditFields'
                - properties:
                    operatorId:
                      type: integer
                      description: Edit operator by id or create new operator if is null
                      nullable: true
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    delete:
      tags:
        - private
        - points
        - delete
      security:
        - BearerAuth: [ ]
      summary: Apply for Point removal by User
      operationId: deletePrivatePointsById
      parameters:
        - $ref: './parameters/PointId.yaml'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: The User's reason to remove point
                  example: Пункт перевезли в соседний двор
                photoset:
                  type: array
                  items:
                    type: integer
                    description: Preloaded Photo ID
      responses:
        202:
          description: Point removal request accepted
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          message:
                            type: string
                            example: Point removal request accepted

        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /public/fractions:
    $ref: './paths/PublicFractions.yaml'

  /public/operators:
    $ref: './paths/PublicOperators.yaml'

  /public/operators/{operatorId}:
    $ref: './paths/PublicOperatorsId.yaml'

  /private/ratings:
    post:
      tags:
        - private
        - ratings
        - post
      security:
        - BearerAuth: [ ]
      summary: Add like/dislike to the Point
      operationId: postPrivateRatings
      description: New value rewrites previous in database. Neutral status deletes record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pointId:
                  type: integer
                  description: A Point ID to like or dislike
                reaction:
                  type: string
                  description: Add like, dislike or neutral user's reaction
                  enum:
                    - like
                    - dislike
                    - neutral
              required:
                - pointId
                - reaction
              example:
                pointId: 324
                reaction: like
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /private/favorites:
    post:
      tags:
        - private
        - favorites
        - post
      security:
        - BearerAuth: [ ]
      summary: Add favorite mark to the Point
      operationId: postPrivateFavorites
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pointId:
                  type: integer
                  description: A Point ID add to favorite
              required: [ pointId ]
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /public/search:
    $ref: './paths/PublicSearch.yaml'

  /subscriptions:
    $ref: './paths/Subscriptions.yaml'

  /auth/sessions:
    get:
      tags:
        - auth
        - get
      summary: Request verification code by email
      operationId: getAuthSessions
      parameters:
        - in: query
          name: email
          schema:
            type: string
          required: true
          description: User's email to send verification code
          example: user@example.com
      responses:
        200:
          $ref: '#/components/responses/EmptySuccess'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    post:
      tags:
        - auth
        - post
      summary: 'Post new user session (login)'
      operationId: postAuthSessions
      description: Temporarily we can use User's ID as a result. In future versions we should return ID of logged session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    byCode:
                      type: boolean
                      description: If `bycode` presents in query, accept { email and verification code } instead of { email and passphrase }
                    username:
                      type: string
                      description: user login
                    passphrase:
                      type: string
                      description: user password
                  example:
                    byCode: False
                    username: 'user@example.com'
                    passphrase: 'sdf3-bg2fd-234d'
                  required:
                    - byCode
                    - username
                    - passphrase
                - type: object
                  properties:
                    byCode:
                      type: boolean
                      description: If `bycode` presents in query, accept { email and verification code } instead of { email and passphrase }
                    username:
                      type: string
                      description: user login
                    code:
                      type: string
                      description: verification code from email
                  example:
                    byCode: True
                    username: 'user@example.com'
                    code: '2314'
                  required:
                    - byCode
                    - username
                    - code
      responses:
        200:
          description: Succesfull login
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          bearer:
                            type: string
                            description: JWT token
                          exipiration:
                            type: string
                            format: date-time
                            description: Datetime of JWT expiration. Client should refresh token before this deadline.
                        example:
                          bearer: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5MjE4ODgzMjI1IiwibmFtZSI6IlNlbSBQbyIsImlhdCI6MTUxNjIzOTAyMn0.bUUovXQPJSdhCE8HVJaifaSp73BWSHkcKXPadQlzbcI'
                          expiration: '2022-12-19T16:39:57+03:00'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'

  /auth/sessions/current:
    get:
      tags:
        - auth
        - get
      security:
        - BearerAuth: [ ]
      operationId: getAuthSessionsCurrent
      summary: 'Get information about logged in user'
      parameters:
        - in: query
          name: refresh
          schema:
            type: boolean
          required: false
          description: Whether the method should return a new token
      responses:
        200:
          description: Currently logged in user
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '#/components/schemas/User'
                          - properties:
                              userId:
                                type: integer
                                description: User ID
                                example: '1024'
                              aor:
                                type: string
                                description: Area of Responsibility geometry in WKT, visible to Moderators only
                                example: 'MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'
                              subscription:
                                allOf:
                                  - $ref: '#/components/schemas/ModeratorSubscription'
                                  - required: [comments, moderation]
                          - required: [userId, firstName, surname, email, role, subscription]
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'

    delete:
      security:
        - BearerAuth: [ ]
      tags:
        - auth
        - delete
      summary: Delete current session (logout)
      operationId: deleteAuthSessionsCurrent
      responses:
        204:
          description: Session deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'

  /auth/users:
    post:
      tags:
        - auth
        - post
      summary: Add new User
      operationId: postAuthUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: User first name
                  example: 'Пётр'
                surname:
                  type: string
                  description: User surname
                  example: 'Сидоров'
                email:
                  type: string
                  description: |
                    User email
                    
                    Cyrillic domain names are not accepted
                  example: 'user@example.com'
                passphrase:
                  type: string
                  description: User password
                  example: 'gfd-4fr-fgfg'
                avatar:
                  type: integer
                  description: Photo set id for user's avatar
                  example: 324
                news:
                  type: boolean
                  description: Flag indicating that user wants to subscript on the hubspot
                  example: true
              required:
                - firstName
                - email
                - passphrase
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /auth/users/{userId}:
    patch:
      tags:
        - auth
        - patch
      security:
        - BearerAuth: [ ]
      summary: Change User's information
      operationId: patchAuthUsersById
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        description: |
          use values for clearing fields:
           - surname: "\_REMOVE\_"
           - avatar: -1
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: User first name
                  example: 'Пётр'
                surname:
                  type: string
                  description: User surname
                  example: 'Сидоров'
                email:
                  type: string
                  description: User email
                  example: 'user@example.com'
                passphrase:
                  type: string
                  description: User password
                  example: 'gfd-4fr-fgfg'
                avatar:
                  type: integer
                  description: Photo set id for user's avatar
                  example: 324
                subscription:
                  $ref: '#/components/schemas/ModeratorSubscription'

      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'
    delete:
      tags:
        - delete
        - auth
      security:
        - BearerAuth: [ ]
      summary: Delete User
      operationId: deleteUserById
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        204:
          description: User deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /public/comments:
    $ref: './paths/PublicComments.yaml'

  /private/comments:
    get:
      tags:
        - private
        - comments
        - get
      security:
        - BearerAuth: [ ]
      summary: Get list of comments of selected Point
      operationId: getPrivateComments
      description: |
        List of comment includes two parts:
          - `size` comments with parentCommentId == 0
          - all replies (comments with parentCommentId values within first list)
      parameters:
        - in: query
          name: pointId
          required: true
          schema:
            type: integer
          description: The Point ID
        - $ref: './parameters/QuerySize.yaml'
        - $ref: './parameters/Offset.yaml'
      responses:
        200:
          description: A list of comments
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalResults:
                            description: Number of comments excepting DELMOD, DELME status
                            type: number
                          comments:
                            type: array
                            items:
                              $ref: '#/components/schemas/CommentAuthUser'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    post:
      tags:
        - private
        - comments
        - post
      security:
        - BearerAuth: [ ]
      summary: Post new comment to selected Point
      operationId: postPrivateComments
      requestBody:
        description: New comment object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pointId:
                  type: integer
                  description: Point ID to add comment to
                message:
                  type: string
                  description: Text of the comment
                  example: 'This point is one of the best'
                parentCommentId:
                  type: integer
                  nullable: true
                  description: ID of a parent comment if the comment is a reply
                  example: '12'
                photoset:
                  type: array
                  items:
                    type: integer
                    description: Preloaded Photo ID
              required:
                - pointId
                - message
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'

  /moderator/comments:
    get:
      tags:
        - moderator
        - comments
        - get
      security:
        - BearerAuth: [ ]
      summary: Get list of comments of selected Point for Moderator
      operationId: getModeratorComments
      description: |
        List of comment includes two parts:
          - `size` comments with parentCommentId == 0
          - all replies (comments with parentCommentId values within first list)
        Also each comment includes status field for Moderator
      parameters:
        - in: query
          name: pointId
          required: true
          schema:
            type: integer
          description: The Point ID
        - $ref: './parameters/QuerySize.yaml'
        - $ref: './parameters/Offset.yaml'
      responses:
        200:
          description: A list of comments with status field
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalResults:
                            type: number
                            description: Number of comments excepting DELMOD, DELME status
                          newComments:
                            type: number
                            description: Number of comments with NEW status
                          iCareComments:
                            type: number
                            description: Number of comments with ICARE status
                          comments:
                            type: array
                            items:
                              $ref: '#/components/schemas/CommentModerator'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    delete:
      tags:
        - moderator
        - comments
        - delete
      security:
        - BearerAuth: [ ]
      summary: Delete all Comments of the Point by Moderator
      operationId: deleteModeratorCommentsByPointId
      parameters:
        - in: query
          name: pointId
          required: true
          schema:
            type: integer
          description: The Point ID

      responses:
        204:
          description: Comments deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /private/comments/{commentId}:
    patch:
      tags:
        - private
        - comments
        - patch
      security:
        - BearerAuth: [ ]
      summary: Patch Comment
      operationId: patchPrivateCommentsById
      parameters:
        - $ref: './parameters/CommentId.yaml'
      requestBody:
        description: |
          Patched Comment object. At least one parameter required.
          
          use values for clearing fields:
          - photoset: [ ]
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: New text of the comment
                  example: 'This point is one of the best'
                photoset:
                  type: array
                  items:
                    type: integer
                    description: Preloaded Photo ID
              minProperties: 1
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    delete:
      tags:
        - private
        - comments
        - delete
      security:
        - BearerAuth: [ ]
      summary: Delete Comment
      operationId: deletePrivateCommentsById
      parameters:
        - $ref: './parameters/CommentId.yaml'
      responses:
        204:
          description: Comment deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /private/photos:
    post:
      tags:
        - private
        - photos
        - post
      security:
        - BearerAuth: [ ]
      summary: Post new photo. Returns PhotoId.
      operationId: postPrivatePhotos
      requestBody:
        description: Binary photo
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  format: binary
      responses:
        200:
          description: Succesfully posted photo
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          photoId:
                            type: integer
                            example: 12
                          path:
                            type: string
                            example: 881b7_20221212-174634.jpeg
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'

  /public/ecoadvices/random:
    $ref: './paths/PublicEcoadvicesRandom.yaml'

  /public/ecoadvices:
    $ref: './paths/PublicEcoadvices.yaml'

  /admin/ecoadvices:
    post:
      tags:
        - admin
        - ecoadvices
        - post
      security:
        - BearerAuth: [ ]
      summary: Post new ecoadvice
      operationId: postAdminEcoadvices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                advice:
                  type: string
              required: [advice]
              example:
                advice: 'Используйте заварочный чайник вместо одноразовых пакетиков.'
      responses:
        '200':
          $ref: '#/components/responses/ObjectPosted'
        '400':
          $ref: './responses/BadRequest.yaml'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: './responses/AccessDenied.yaml'
        '5XX':
          $ref: './responses/ServerError.yaml'

  /admin/ecoadvices/{adviceId}:
    put:
      tags:
        - admin
        - ecoadvices
        - put
      security:
        - BearerAuth: [ ]
      summary: Edit ecoadvice
      operationId: putAdminEcoadvicesById
      description: |
        Don't forget! The HTTP PUT request method creates a new resource
        or replaces a representation of the target resource with the request payload.
        Please see https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 for details.
      parameters:
        - in: path
          name: adviceId
          required: true
          schema:
            type: integer
            example: 3
          description: The Ecoadvice ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                advice:
                  type: string
              required: [advice]
              example:
                advice: 'Используйте заварочный чайник вместо одноразовых пакетиков.'
      responses:
        '200':
          $ref: '#/components/responses/ObjectPosted'
        '400':
          $ref: './responses/BadRequest.yaml'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: './responses/AccessDenied.yaml'
        '5XX':
          $ref: './responses/ServerError.yaml'

    delete:
      tags:
        - admin
        - ecoadvices
        - delete
      security:
        - BearerAuth: [ ]
      summary: Delete Ecoadvice
      operationId: deleteAdminEcoadvicesById
      parameters:
        - in: path
          name: adviceId
          required: true
          schema:
            type: integer
          description: The Ecoadvice ID
      responses:
        '204':
          description: Ecoadvice deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: './responses/AccessDenied.yaml'
        '404':
          $ref: './responses/NotFound.yaml'
        '5XX':
          $ref: './responses/ServerError.yaml'

  /moderator/comments/{commentId}:
    patch:
      tags:
        - moderator
        - comments
        - patch
      security:
        - BearerAuth: [ ]
      summary: Patch Comment
      operationId: patchModeratorCommentsById
      parameters:
        - $ref: './parameters/CommentId.yaml'
      requestBody:
        description: New Comment status.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                statusSlug:
                  type: string
                  description: New status of the Comment
                  enum:
                    - NEW
                    - ICARE
                    - NULL
                  example: 'ICARE'
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    delete:
      tags:
        - moderator
        - comments
        - delete
      security:
        - BearerAuth: [ ]
      summary: Delete Comment by Moderator
      operationId: deleteModeratorCommentsById
      parameters:
        - $ref: './parameters/CommentId.yaml'
        - in: query
          name: mode
          schema:
            type: string
            enum:
              - single
              - child
            default: single
          required: false
          description: Mode of deleting comment(s) - 'child' will delete also replies

      responses:
        204:
          description: Comment deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /moderator/points:
    get:
      tags:
        - moderator
        - points
        - get
      security:
        - BearerAuth: [ ]
      summary: Get list of points with short description with Moderator's fields
      operationId: getModeratorPoints
      parameters:
        - $ref: './parameters/BBox.yaml'
        - $ref: './parameters/QuerySize.yaml'
        - $ref: './parameters/Fractions.yaml'
        - $ref: './parameters/RestrictedPoint.yaml'
        - $ref: './parameters/BusinessHours.yaml'
        - $ref: './parameters/Offset.yaml'
        - $ref: '#/components/parameters/MyComments'
        - $ref: '#/components/parameters/MyPoints'
        - $ref: '#/components/parameters/MyEdits'
        - $ref: '#/components/parameters/MyFavorites'
        - $ref: '#/components/parameters/MyAoR'
        - $ref: '#/components/parameters/NeedModeration'
        - $ref: '#/components/parameters/DisabledPoint'
        - $ref: '#/components/parameters/NewComments'
        - $ref: '#/components/parameters/ICare'
        - $ref: '#/components/parameters/MissModerator'
        - $ref: '#/components/parameters/SortBy'
      responses:
        200:
          description: A list of points with Moderator's fields
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalResults:
                            type: number
                          points:
                            type: array
                            items:
                              $ref: '#/components/schemas/PointShortModerator'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'
    post:
      tags:
        - moderator
        - points
        - post
      summary: Add new Point by Moderator
      operationId: postModeratorPoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/PointEditFields'
                - required:
                  - title
                  - address
                  - fractions
                  - pointDescription
                  - schedule
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /moderator/points/{pointId}:
    get:
      tags:
        - moderator
        - points
        - get
      security:
        - BearerAuth: [ ]
      summary: Get full information about Point with Moderator related data
      operationId: getModeratorPointsById
      parameters:
        - $ref: './parameters/PointId.yaml'
      responses:
        200:
          description: Full Point information with Moderator related data
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PointModerator'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    patch:
      tags:
        - moderator
        - points
        - patch
      security:
        - BearerAuth: [ ]
      summary: Edit information about Point
      operationId: patchModeratorPointsById
      parameters:
        - $ref: './parameters/PointId.yaml'
      requestBody:
        required: true
        description: |
         use values for clearing fields:
         - addressDescription, scheduleDescription: "\_REMOVE\_"
         - validDates, photoset: [ ]
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/PointEditFields'
                - properties:
                    enable:
                      type: boolean
                      description: flag to manually activate point if it was disabled
                      example: true
                    operatorId:
                      type: integer
                      description: Edit operator by id or create new operator if is null
                      nullable: true
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

    delete:
      tags:
        - moderator
        - points
        - delete
      security:
        - BearerAuth: [ ]
      summary: Apply for Point removal by User
      operationId: deleteModeratorPointsById
      parameters:
        - $ref: './parameters/PointId.yaml'
      responses:
        202:
          description: Point removal request accepted
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          message:
                            type: string
                            example: Point removal request accepted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /moderator/operators:
    post:
      tags:
        - moderator
        - operators
        - post
      security:
       - BearerAuth: [ ]
      summary: Post new point operator
      operationId: postModeratorOperators
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
               - $ref: './schemas/OperatorIn.yaml'
               - required: [title]
      responses:
        '200':
          $ref: '#/components/responses/ObjectPosted'
        '400':
          $ref: './responses/BadRequest.yaml'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: './responses/AccessDenied.yaml'
        '5XX':
          $ref: './responses/ServerError.yaml'

  /moderator/operators/{operatorId}:
    parameters:
      - $ref: './parameters/OperatorId.yaml'
    patch:
      tags:
        - moderator
        - operators
        - patch
      security:
        - BearerAuth: [ ]
      summary: Edit operator fields
      operationId: patchModeratorOperators
      requestBody:
        required: true
        description: |
          use for remove:
          - address: "\_REMOVE\_"
          - sites, phones, emails: []
        content:
          application/json:
            schema:
              $ref: './schemas/OperatorIn.yaml'
      responses:
        '200':
          $ref: '#/components/responses/ObjectPosted'
        '400':
          $ref: './responses/BadRequest.yaml'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: './responses/AccessDenied.yaml'
        '404':
          $ref: './responses/NotFound.yaml'
        '5XX':
          $ref: './responses/ServerError.yaml'

  /moderator/points/bulk:
    get:
      tags:
        - moderator
        - points
        - bulk
        - get
      security:
        - BearerAuth: [ ]
      summary: Get points data in csv according to filters
      operationId: getModeratorPointsBulk
      parameters:
        - $ref: './parameters/BBox.yaml'
        - $ref: './parameters/Fractions.yaml'
        - $ref: './parameters/RestrictedPoint.yaml'
        - $ref: './parameters/BusinessHours.yaml'
        - $ref: '#/components/parameters/MyComments'
        - $ref: '#/components/parameters/MyPoints'
        - $ref: '#/components/parameters/MyEdits'
        - $ref: '#/components/parameters/MyFavorites'
        - $ref: '#/components/parameters/MyAoR'
        - $ref: '#/components/parameters/NeedModeration'
        - $ref: '#/components/parameters/DisabledPoint'
        - $ref: '#/components/parameters/NewComments'
        - $ref: '#/components/parameters/ICare'
        - $ref: '#/components/parameters/MissModerator'
      responses:
        200:
          description: CSV file with points (<a target="_blank" href="./bulk.html">description with example</a>)
          content:
            text/csv:
              schema:
                type: string
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'
    post:
      tags:
        - moderator
        - points
        - bulk
        - post
      security:
        - BearerAuth: [ ]
      summary: Edit points via bulk upload
      operationId: postModeratorPointsBulk
      requestBody:
        required: true
        description: Upload CSV file (<a target="_blank" href="./bulk.html">description with example</a>)
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  format: binary
      responses:
        '200':
          $ref: '#/components/responses/ObjectPosted'
        '400':
          $ref: './responses/BadRequest.yaml'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '5XX':
          $ref: './responses/ServerError.yaml'

  /moderator/operators/bulk:
    get:
      tags:
        - moderator
        - operators
        - bulk
        - get
      security:
        - BearerAuth: [ ]
      summary: Get operators data in csv
      operationId: getModeratorOperatorsBulk
      responses:
        200:
          description: CSV file with operators (<a target="_blank" href="./operator_bulk.html">description</a>)
          content:
            text/csv:
              schema:
                type: string
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /moderator/fixes:
    get:
      tags:
        - moderator
        - fixes
        - get
      security:
        - BearerAuth: []
      summary: Get list of fixes for Point
      operationId: getModeratorFixesByPointId
      parameters:
        - in: query
          name: pointId
          required: true
          schema:
            type: integer
          description: The Point ID
      responses:
        200:
          description: A list of fixes
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        description: Update information for Point
                        type: array
                        items:
                          anyOf:
                            - $ref: '#/components/schemas/FixAdd'
                            - $ref: '#/components/schemas/FixEdit'
                            - $ref: '#/components/schemas/FixDelete'

  /moderator/fixes/{fixId}:
    patch:
      tags:
        - moderator
        - fixes
        - patch
      security:
        - BearerAuth: [ ]
      summary: Manage Fixes by Moderator
      operationId: patchModeratorFixesById
      parameters:
        - $ref: '#/components/parameters/FixId'
      requestBody:
        description: |
          Fix management commands
        
          use values for clearing fields in yesBut:
            - addressDescription, scheduleDescription: "\_REMOVE\_"
            - validDates, photoset: [ ]
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/FixManagementSimple'
                - $ref: '#/components/schemas/FixManagementAdd'
                - $ref: '#/components/schemas/FixManagementEdit'
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /public/headers:
    get:
      tags:
        - public
        - headers
        - get
      summary: Get list of dynamic buttons
      operationId: getHeader
      responses:
        200:
          description: A list of buttons
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/HeadButton'

  /admin/users:
    get:
      tags:
        - admin
        - users
        - get
        - search
      security:
        - BearerAuth: [ ]
      summary: Search users by Admin
      operationId: searchUsersByAdmin
      parameters:
        - $ref: '#/components/parameters/Email'
      responses:
        200:
          description: User's data
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        type: array
                        maxItems: 1
                        items:
                          allOf:
                            - $ref: '#/components/schemas/User'
                            - properties:
                                userId:
                                  type: integer
                                  description: User ID
                                  example: '1024'
                            - required: [userId, firstName, surname, email, role]
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /admin/users/{userId}:
    get:
      tags:
        - admin
        - users
        - get
      security:
        - BearerAuth: [ ]
      summary: Get user info by Admin
      operationId: getUserByAdmin
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        200:
          description: Requested user info
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './schemas/SuccessFlag.yaml'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '#/components/schemas/User'
                          - properties:
                              userId:
                                type: integer
                                description: User ID
                                example: '1024'
                              aor:
                                type: string
                                description: Area of Responsibility geometry in WKT, visible to Moderators only
                                example: 'MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'
                              subscription:
                                allOf:
                                  - $ref: '#/components/schemas/ModeratorSubscription'
                                  - required: [ comments, moderation ]
                          - required: [ userId, firstName, surname, email, role, subscription ]
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'
    patch:
      tags:
        - admin
        - users
        - patch
      security:
        - BearerAuth: [ ]
      summary: Change User's information by Admin
      operationId: patchUsersByAdmin
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        description: |
          use values for clearing fields:
           - surname, aor: "\_REMOVE\_"
           - avatar: -1
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: User first name
                  example: 'Пётр'
                surname:
                  type: string
                  description: User surname
                  example: 'Сидоров'
                email:
                  type: string
                  description: User email
                  example: 'user@example.com'
                passphrase:
                  type: string
                  description: User password
                  example: 'gfd-4fr-fgfg'
                avatar:
                  type: integer
                  description: Photo set id for user's avatar
                  example: 324
                role:
                  type: string
                  enum:
                    - user
                    - moderator
                  description: User's role
                  example: 'moderator'
                subscription:
                  $ref: '#/components/schemas/ModeratorSubscription'
                aor:
                  type: string
                  description: Area of Responsibility geometry in WKT, visible to Moderators only
                  example: 'MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'
    delete:
      tags:
        - admin
        - users
        - delete
      security:
        - BearerAuth: [ ]
      summary: Delete any User by Admin
      operationId: deleteUserByAdmin
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        204:
          description: User deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: './responses/AccessDenied.yaml'
        404:
          $ref: './responses/NotFound.yaml'
        5XX:
          $ref: './responses/ServerError.yaml'

  /private/photoset:
    post:
      tags:
        - post
        - photos
      security:
        - BearerAuth: [ ]
      summary: Create new photo set with photo ids
      operationId: postPhotoset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                photoset:
                  type: array
                  description: Photo ids
                  minLength: 1
                  items:
                    type: integer
                    format: id
                    description: photo id
              required: [photoset]
      responses:
        200:
          $ref: '#/components/responses/ObjectPosted'
        400:
          $ref: './responses/BadRequest.yaml'
        401:
          $ref: '#/components/responses/Unauthorized'
        5XX:
          $ref: './responses/ServerError.yaml'

  /tiles/get_points/{z}/{x}/{y}.pbf:
    get:
      tags:
        - tiles
        - get
      summary: Get points in MVT
      operationId: getTilesPoints
      description: |
        Get points in Mapbox Vector Tiles format and filter them by:
          - fractions
          - restricted
          - business hours
      parameters:
        - $ref: '#/components/parameters/MartinZ'
        - $ref: '#/components/parameters/MartinX'
        - $ref: '#/components/parameters/MartinY'
        - $ref: '#/components/parameters/MartinBusinessHours'
        - $ref: './parameters/FractionIds.yaml'
        - $ref: '#/components/parameters/MartinUserId'
        - $ref: '#/components/parameters/MartinRestrictedPoint'
        - $ref: '#/components/parameters/MartinMyComments'
        - $ref: '#/components/parameters/MartinMyPoints'
        - $ref: '#/components/parameters/MartinMyEdits'
        - $ref: '#/components/parameters/MartinMyAoR'
        - $ref: '#/components/parameters/MartinNeedModeration'
        - $ref: '#/components/parameters/MartinDisabledPoint'
        - $ref: '#/components/parameters/MartinNewComments'
        - $ref: '#/components/parameters/MartinICare'
        - $ref: '#/components/parameters/MartinMissModerator'
        - $ref: '#/components/parameters/MartinNoCache'
      responses:
        '200':
          description: Points in MVT format
          content:
            application/protobuf:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MVTPoint'
        '5XX':
          $ref: './responses/ServerError.yaml'

  /tiles/get_hexaclusters/{z}/{x}/{y}.pbf:
    get:
      tags:
        - tiles
        - get
      summary: Get points in MVT
      operationId: getTilesHexaclusters
      description: |
        Get cluster points in Mapbox Vector Tiles formt and filter them by:
          - fractions
          - restricted
          - business hours
      parameters:
        - $ref: '#/components/parameters/MartinZ'
        - $ref: '#/components/parameters/MartinX'
        - $ref: '#/components/parameters/MartinY'
        - $ref: '#/components/parameters/MartinBusinessHours'
        - $ref: './parameters/FractionIds.yaml'
        - $ref: '#/components/parameters/MartinUserId'
        - $ref: '#/components/parameters/MartinRestrictedPoint'
        - $ref: '#/components/parameters/MartinMyComments'
        - $ref: '#/components/parameters/MartinMyPoints'
        - $ref: '#/components/parameters/MartinMyEdits'
        - $ref: '#/components/parameters/MartinMyAoR'
        - $ref: '#/components/parameters/MartinNeedModeration'
        - $ref: '#/components/parameters/MartinDisabledPoint'
        - $ref: '#/components/parameters/MartinNewComments'
        - $ref: '#/components/parameters/MartinICare'
        - $ref: '#/components/parameters/MartinMissModerator'
        - $ref: '#/components/parameters/MartinNoCache'
      responses:
        '200':
          description: Points clusters in MVT format
          content:
            application/protobuf:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MVTPointsCluster'
        '5XX':
          $ref: './responses/ServerError.yaml'

components:
  schemas:
    # Response schemas
    PostedObjectId:
      type: object
      allOf:
      - $ref: './schemas/SuccessFlag.yaml'
      - type: object
        properties:
          data:
            type: integer
            description: ID of the new posted object
            example: '32'

    ClientUnauthorizedMessage:
      allOf:
      - $ref: './schemas/SuccessFlag.yaml'
      - type: object
        properties:
          errors:
            type: object
            properties:
              message:
                type: string
                description: Human readable error message
      example:
        isSuccess: false
        errors:
          message: "User's password has expired"

    # Base objects
    Reaction:
      type: string
      description: Like or dislike user's reaction
      enum:
        - like
        - dislike

    PointEditFields:
      type: object
      properties:
        title:
          type: string
          maxLength: 1000
          minLength: 1
          description: Point title
          example: 'Пункт приёма батареек'
        restricted:
          type: boolean
          description: Point restricted access
          example: 'false'
        geom:
          type: string
          description: Point geometry in WKT
          example: 'POINT (82.927810142519 55.0289362348260)'
        precise:
          type: boolean
          description: A flag of the presence of exact coordinates
        address:
          type: string
          minLength: 1
          maxLength: 1000
          description: Point postal address
          example: 'Москва, ул. Киевская, 6'
        addressDescription:
          type: string
          maxLength: 5000
          description: Point postal address description
          example: 'Вход под арку'
        fractions:
          type: array
          description: Array of fraction's slugs
          minItems: 1
          maxItems: 13
          uniqueItems: true
          items:
            type: string
            enum:
              - STEKLO
              - PLASTIK
              - BUMAGA
              - METALL
              - BYTOVAJA_TEHNIKA
              - ODEZHDA
              - TETRA_PAK
              - OPASNYE_OTHODY
              - LAMPOCHKI
              - KRYSHECHKI
              - BATAREJKI
              - INOE
              - SHINY
          example: '["STEKLO", "PLASTIK"]'
        validDates:
          type: array
          maxItems: 100
          description: Point opening dates
          items:
            type: object
            minProperties: 2
            maxProperties: 2
            properties:
              validFrom:
                type: string
                format: date
                example: '2022-07-01'
                description: Should be before validThrough, years 1900-2100
              validThrough:
                type: string
                format: date
                example: '2022-07-15'
                description: Should be after validFrom, years 1900-2100
        schedule:
          $ref: './schemas/Schedule.yaml'
        scheduleDescription:
          type: string
          maxLength: 5000
          description: Description of Point's schedule
        photoset:
          type: array
          maxItems: 20
          items:
            type: integer
            description: Preloaded Photo ID
        pointDescription:
          type: string
          minLength: 1
          maxLength: 5000
          format: html
          description: Description of Point with BIU, bullets, links
        operator:
          oneOf:
            - $ref: './schemas/OperatorIn.yaml'
            - type: integer
              description: ID of Point's Operator

    PointShortAuthUser:
      allOf:
      - $ref: './schemas/PointShortPublic.yaml'
      - type: object
        properties:
          iLike:
            type: boolean
            description: True if the User liked the Point
          iDisike:
            type: boolean
            description: True if the User disliked the Point
          myFavorite:
            type: boolean
            description: True if the User mark the Point as favorite
          myPoint:
            type: boolean
            description: True if the Point was added by the User
          myEdits:
            type: boolean
            description: True if the Point was edited by the User
          disabled:
            type: boolean
            description: This field can be True if the User has added the Point but moderation is still in progress

    PointShortModerator:
      allOf:
      - $ref: '#/components/schemas/PointShortAuthUser'
      - $ref: '#/components/schemas/PointModeratorFields'

    PointModeratorFields:
      type: object
      properties:
        myAoR:
          type: boolean
          description: True if the Point is in Moderator's Area of Responsibility
        needMod:
          type: boolean
          description: True if the Point needs moderation process
        missMod:
          type: boolean
          description: True if the Point misses Moderator
        disabled:
          type: boolean
          description: True if the Point is disabled
        numberOfNewComments:
          type: integer
          description: Number of Point's new Comments
          example: 2
        numberOfICareComments:
          type: integer
          description: Number of Point's new Comments
          example: 2
        creator:
          $ref: '#/components/schemas/User'

    PointAuthUser:
      allOf:
        - $ref: './schemas/PointPublic.yaml'
        - type: object
          properties:
            iLike:
              type: boolean
              description: True if user liked the Point
            iDisike:
              type: boolean
              description: True if user disliked the Point
            myFavorite:
              type: boolean
              description: True if the Point is User's favorite
            myPoint:
              type: boolean
              description: True if the Point was added by the User
            myEdits:
              type: boolean
              description: True if the Point was edited by the User
            inProgress:
              type: string
              enum: [add, edit, disable]
              description: This field is not empty only if the User adds/edits/deletes the Point and moderation is in progress
            disabled:
              type: boolean
              description: This field can be True if the User has added the Point but moderation is still in progress

    PointModerator:
      allOf:
        - $ref: '#/components/schemas/PointAuthUser'
        - $ref: '#/components/schemas/PointModeratorFields'

    CommentAuthUser:
      allOf:
        - $ref: './schemas/Comment.yaml'
        - type: object
          properties:
            myComment:
              type: boolean
              description: The Comment belongs to User, so edit and delete are available

    CommentModerator:
      allOf:
      - $ref: '#/components/schemas/CommentAuthUser'

    MVTPointsCluster:
      description: Properties of cluster of points in Mapbox Vector Tile
      type: object
      properties:
        total:
          type: number
          description: number of points in cluster
        fractions:
          type: string
          example: '{1,2,6}'
          description: comma separated string of fractions in cluster
        pointId:
          type: number
          description: Id of Point if it is the only one in the cluster
      required:
        - total
        - fractions
    MVTPoint:
      description: Properties of single point in Mapbox Vector Tile
      type: object
      properties:
        id:
          type: number
          description: Id of Point
        title:
          type: string
          description: Point Title
          example: 'Пункт приёма батареек'
        fractions:
          type: string
          example: '{1,2,6}'
          description: comma separated string of fractions in cluster
        # fixme: duplicated property
        restricted:
          type: boolean
          description: Point is on restricted area
          example: false
        inProgress:
          type: string
          enum: [ add, edit, disable ]
          description: This field is not empty only if the User adds/edits/deletes the Point and moderation is in progress
        disabled:
          type: boolean
          description: This field can be True if the User has added the Point but moderation is still in progress
        myAoR:
          type: boolean
          description: True if the Point is in Moderator's Area of Responsibility
        needMod:
          type: boolean
          description: True if the Point needs moderation process
        missMod:
          type: boolean
          description: True if the Point misses Moderator
          
    User:   
      type: object
      allOf:
        - $ref: './schemas/UserBase.yaml'
        - properties:
            email:
              type: string
              description: User's email
              example: 'user@example.com'

    FieldModerationStatus:
      description: Statuses of field moderation
      type: string
      enum:
        - new
        - accepted
        - rejected
      example: 'new'

    FixFieldsSet:
      type: object
      description: List of fields in edit Fix
      properties:
        title:
          $ref: '#/components/schemas/FieldModerationStatus'
        address:
          $ref: '#/components/schemas/FieldModerationStatus'
        geom:
          $ref: '#/components/schemas/FieldModerationStatus'
        restricted:
          $ref: '#/components/schemas/FieldModerationStatus'
        fractions:
          $ref: '#/components/schemas/FieldModerationStatus'
        addressDescription:
          $ref: '#/components/schemas/FieldModerationStatus'
        pointDescription:
          $ref: '#/components/schemas/FieldModerationStatus'
        validDates:
          $ref: '#/components/schemas/FieldModerationStatus'
        schedule:
          $ref: '#/components/schemas/FieldModerationStatus'
        scheduleDescription:
          $ref: '#/components/schemas/FieldModerationStatus'
        photos:
          $ref: '#/components/schemas/FieldModerationStatus'
        operator:
          $ref: '#/components/schemas/FieldModerationStatus'
        operatorTitle:
          $ref: '#/components/schemas/FieldModerationStatus'
        operatorSites:
          $ref: '#/components/schemas/FieldModerationStatus'
        operatorEmails:
          $ref: '#/components/schemas/FieldModerationStatus'
        operatorPhones:
          $ref: '#/components/schemas/FieldModerationStatus'

    FixAdd:
      description: Fix of Add type
      type: object
      properties:
        fixId:
          type: integer
          description: ID of fix
          example: 5
        timestamp:
          type: string
          format: date-time
          description: Datetime of fix
        fixman:
          $ref: '#/components/schemas/User'
        operation:
          type: string
          description: Must be 'add'
          enum:
            - add
          example: 'add'
        moderation:
          type: string
          description: Moderation state
          enum:
            - progress
          example: 'progress'

    FixEdit:
      description: Fix of Edit type
      type: object
      properties:
        fixId:
          type: integer
          description: ID of fix
          example: 5
        timestamp:
          type: string
          format: date-time
          description: Datetime of fix
        fixman:
          $ref: '#/components/schemas/User'
        operation:
          type: string
          description: Must be 'edit'
          enum:
            - edit
          example: 'edit'
        moderation:
          type: string
          description: Moderation state
          enum:
            - progress
          example: 'progress'
        rawData:
          allOf:
            - $ref: './schemas/PointShortBase.yaml'
            - $ref: './schemas/PointExtraFields.yaml'
        fieldsStatus:
          $ref: '#/components/schemas/FixFieldsSet'

    FixDelete:
      description: Fix of Add type
      type: object
      properties:
        fixId:
          type: integer
          description: ID of fix
          example: 5
        timestamp:
          type: string
          format: date-time
          description: Datetime of fix
        fixman:
          $ref: '#/components/schemas/User'
        operation:
          type: string
          description: Must be 'add'
          enum:
            - add
          example: 'add'
        moderation:
          type: string
          description: Moderation state
          enum:
            - progress
          example: 'progress'
        photos:
          type: array
          items:
            $ref: './schemas/Photo.yaml'
        reason:
          type: string
          description: deactivation reason of the user

    FixManagementSimple:
      description: Fix accept or reject with reason
      type: object
      properties:
        moderation:
          type: string
          enum:
            - done
            - reject
        reason:
          type: string
          description: Rejection reason
      required:
        - moderation

    FixManagementAdd:
      description: Fix accept for new Point
      type: object
      properties:
        moderation:
          type: string
          enum:
            - done
        yesBut:
          $ref: '#/components/schemas/PointEditFields'

    FixManagementEdit:
      description: Fix management of individual fields
      type: object
      properties:
        coPerField:
          $ref: '#/components/schemas/FixFieldsSet'
        yesBut:
          $ref: '#/components/schemas/PointEditFields'

    HeadButton:
      description: Header button data
      type: object
      properties:
        order:
          type: integer
          description: Order number of button in header row
          example: 1
        title:
          type: string
          description: Inner text of button
          example: 'Поддержите нас'
        linkType:
          type: string
          description: |
            Where to open link:
            - iframe: over the app in iframe, needs full iframe code, see example;
            - thistab: open link in the same browser tab where app is;
            - newtab: open link in a new browser tab.
          enum:
            - iframe
            - thistab
            - newtab
        content:
          type: string
          description: Depends on `linkType`. Can be relative url, absolute url of iframe tag.
          example: '<iframe src=“https://донатьтенаммыхорошие.рф“ width="560" height="400" frameborder="1" allowfullscreen="true" style="position:relative;"></iframe>'

    UserSubscription:
      description: User's subscription info
      type: object
      properties:
        moderation:
          type: boolean
          description: Subscription on point edits and moderation stages
          example: true
        comments:
          type: boolean
          description: Subscription on comment reply
          example: false

    ModeratorSubscription:
      allOf:
        - $ref: "#/components/schemas/UserSubscription"
        - type: object
          properties:
            aor:
              type: boolean
              description: Subscription on points in area of responsibility

  responses:
    EmptySuccess:
      description: Succesfull response without data
      content:
        application/json:
          schema:
            $ref: './schemas/SuccessFlag.yaml'

    ObjectPosted:
      description: Succesfull response with ID of posted object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostedObjectId'

    Unauthorized:
      description: Authentication is required and has failed or has not yet been provided
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientUnauthorizedMessage'

  parameters:
    MartinZ:
      in: path
      name: z
      required: true
      schema:
        type: integer
        example: 12
      description: zoom level

    MartinY:
      in: path
      name: y
      required: true
      schema:
        type: integer
        example: 1358
      description: tile position on y-axis level

    MartinX:
      in: path
      name: x
      required: true
      schema:
        type: integer
        example: 2494
      description: tile position on x-axis level

    FixId:
      in: path
      name: fixId
      required: true
      schema:
        type: integer
      description: The Fix ID

    UserId:
      in: path
      name: userId
      required: true
      schema:
        type: integer
      description: User ID
      example: 12

    MartinUserId:
      in: query
      name: user_id
      required: true
      schema:
        type: integer
      description: User ID
      example: 12

    MartinNoCache:
      in: query
      name: nocache
      required: false
      schema:
        type: boolean
      description: Whether to get cached tiles when possible (false) or bypass cache (true)
      example: false

    Email:
      in: query
      name: email
      schema:
        type: string
        format: email
      required: true
      description: User email

    MyPoints:
      in: query
      name: mypoints
      schema:
        type: boolean
      required: false
      description: Points added by me

    MartinMyPoints:
      in: query
      name: mypoints
      schema:
        type: boolean
      required: true
      description: Points added by UserId for martin

    MyComments:
      in: query
      name: mycomments
      schema:
        type: boolean
      required: false
      description: Points with my comments

    MartinMyComments:
      in: query
      name: mycomments
      schema:
        type: boolean
      required: true
      description: Points with UserId comments for martin

    MyEdits:
      in: query
      name: myedits
      schema:
        type: boolean
      required: false
      description: Points edited by me

    MartinMyEdits:
      in: query
      name: myedits
      schema:
        type: boolean
      required: true
      description: Points edited by UserId for martin

    MyFavorites:
      in: query
      name: myfavorites
      schema:
        type: boolean
      required: false
      description: Points marked as my favorite

    MyAoR:
      in: query
      name: myaor
      schema:
        type: boolean
      required: false
      description: Points in my Area of Responsibility

    MartinMyAoR:
      in: query
      name: myaor
      schema:
        type: boolean
      required: true
      description: Points in Area of Responsibility of UserId for martin

    NeedModeration:
      in: query
      name: needmod
      schema:
        type: boolean
      required: false
      description: Points need moderation

    MartinNeedModeration:
      in: query
      name: needmod
      schema:
        type: boolean
      required: true
      description: Points need moderation for martin

    MissModerator:
      in: query
      name: missmod
      schema:
        type: boolean
      required: false
      description: Points without moderator

    MartinMissModerator:
      in: query
      name: missmod
      schema:
        type: boolean
      required: true
      description: Points without moderator for martin

    DisabledPoint:
      in: query
      name: disabled
      schema:
        type: boolean
      required: false
      description: Points including disabled ones

    MartinDisabledPoint:
      in: query
      name: disabled
      schema:
        type: boolean
      required: true
      description: Points including disabled ones for martin

    ICare:
      in: query
      name: icare
      schema:
        type: boolean
      required: false
      description: Points with comments in iCare status

    MartinICare:
      in: query
      name: icare
      schema:
        type: boolean
      required: true
      description: Points with new commments for martin

    NewComments:
      in: query
      name: newcomments
      schema:
        type: boolean
      required: false
      description: Points with new commments

    MartinNewComments:
      in: query
      name: newcomments
      schema:
        type: boolean
      required: true
      description: Points with new commments for martin

    MartinBusinessHours:
      in: query
      name: open
      schema:
        type: string
        enum:
          - now
          - allday
          - any
      required: true
      description: Business hours filter for martin

    MartinRestrictedPoint:
      in: query
      name: restricted
      schema:
        type: boolean
      required: true
      example: false
      description: Points on restricted (`true`) or unrestricted (`false`) area for martin

    SortBy:
      in: query
      name: sortby
      schema:
        type: string
        default: rating
        enum:
          - rating
          - utime_asc
          - utime_desc
      required: false
      description: |
        Mode for sorting points
        - rating: sort by rating (descending)
        - utime_asc: sort by update time (ascending)
        - utime_desc: sort by update time (descending)

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT