sights-api-doc.yaml

openapi: 3.0.0
info:
  description: |
    This documentation gives a detailed specification of Sights
    API, that offers management features for interesting viewpoints
    in the city of Lisbon and serves the Sights android application.
  version: "1.0.0"
  title: Sights API
  contact:
    email: valter.nep@gmail.com
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/Vnepomuceno/sights-api/1.0.0
  - url: 'https://sights.swagger.io/v2'

tags:
  - name: sights
    description: Information about available Sights
  - name: users
    description: Information about users of the Sigths android application
  - name: feedback
    description: Provide feedback about Sights android application

paths:
  '/sights':
    post:
      tags:
        - sights
      summary: Add a new Sight
      operationId: addSight
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: string
                example: "52d7bf7d723e8e0b0cc09138"
        '400':
          description: Bad request
      requestBody:
        $ref: '#/components/requestBodies/ManageSight'
    get:
      tags:
        - sights
      summary: Lists all Sights
      operationId: listSights
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SightsOverviewArray'

  '/sights/{sightId}':
    get:
        tags:
          - sights
        summary: Fetch details about a Sight
        parameters:
          - in: path
            name: sightId
            schema:
              type: string
              format: uuid
            required: true
            description: Id of the Sight
        operationId: getSight
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Sight'

    put:
        tags:
          - sights
        summary: Replace an existing Sight
        parameters:
          - in: path
            name: sightId
            schema:
              type: string
              format: uuid
            required: true
            description: Id of the Sight
        operationId: editSight
        responses:
          '200':
            description: Success
        requestBody:
            $ref: '#/components/requestBodies/ManageSight'

  '/sights/{sightId}/rate':
    post:
      tags:
        - sights
      summary: Submits a rating for a Sight
      parameters:
        - in: path
          name: sightId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the Sight
      operationId: rateSight
      responses:
        '204':
          description: No content
      requestBody:
        $ref: '#/components/requestBodies/RateSight'

  '/sights/{sightId}/favorite':
    post:
      tags:
        - sights
      summary: Submits a favorite for a Sight
      parameters:
        - in: path
          name: sightId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the Sight
      operationId: favoriteSight
      responses:
        '204':
          description: No content

  '/users/{userId}':
    get:
        tags:
          - users
        summary: Fetch details about a user
        parameters:
          - in: path
            name: userId
            schema:
              type: string
              format: uuid
            required: true
            description: ID of the user
        operationId: getUser
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'

  '/feedback':
    post:
        tags:
          - feedback
        summary: Provide feedback about application
        operationId: createFeedback
        responses:
          '201':
            description: Created
            content:
              application/json:
                schema:
                  type: string
                  example: "59be524946d94a68bc10b7fdf446be22"
        requestBody:
          $ref: '#/components/requestBodies/CreateFeedback'

components:
  schemas:
    Sight:
      type: object
      properties:
        id:
          type: string
          format: uuid
        base:
          type: string
          example: "http://tourism.citysdk.cm-lisboa.pt/pois/"
        citySdkId:
          type: string
          example: "52d7bf7d723e8e0b0cc09138"
    SightOverview:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: "Miradouro do Jardim Botânico da Ajuda"
        distanceFromUserInMeters:
          type: integer
          example: 3700
        userArrivesInMinutes:
          type: integer
          example: 20
        rating:
          type: number
          example: 4.5
        favorites:
          type: integer
          example: 18
    SightsOverviewArray:
      type: array
      items:
        $ref: '#/components/schemas/SightOverview'
    ManageSight:
      type: object
      properties:
        base:
          type: string
          example: "http://tourism.citysdk.cm-lisboa.pt/pois/"
        citySdkId:
          type: string
          example: "52d7bf7d723e8e0b0cc09138"
    RateSight:
      type: object
      properties:
        rating:
          type: integer
          example: 3
    User:
      type: object
      properties:
        id:
          type: string
          example: "67e8715a37a945cab72bcc34db08674f"
        username:
          type: string
          example: "vnepomuceno"
        email:
          type: string
          example: "valter.nep@sights.com"
    Feedback:
      type: object
      properties:
        userId:
          type: string
          example: "abd1582b5e00496aa1aa926b2dfedcc7"
        title:
          type: string
          example: "Provide app in Barcelona"
        description:
          type: string
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ullamcorper elit in mollis condimentum. Nunc lacus massa, condimentum vitae quam quis, interdum lacinia leo. Maecenas suscipit metus ut erat finibus semper."
  
  requestBodies:
    ManageSight:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ManageSight'
      description: Sight object
      required: true
    RateSight:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateSight'
      description: Rate Sight object
      required: true
    CreateFeedback:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Feedback'
      description: Create feedback object
      required: true
  
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header