swagger.yaml

openapi: 3.1.0
info:
  title: Pet Matchmaker
  description: |-
    Pet Matchmaker Backend API
  version: 1.0.0
servers:
  - url: https://pet-matchmaker-api-da76dbdc99ce.herokuapp.com/api/v1
tags:
  - name: user
  - name: questions
  - name: questionnaire submissions
  - name: petfinder animals
paths:
  /users:
    get:
      tags:
        - user
      summary: Get a user
      description: Search for a user by username
      parameters:
        - in: query
          name: username
          schema:
            type: string
            examples: [something_unique]
          required: true
          description: The username to login
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "422":
          description: Non-existent user or missing username
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      tags:
        - user
      summary: Create a new user.
      description: Create a new user with a unique username.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
        required: true
      responses:
        "201":
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "422":
          description: Non-unique username or missing username
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /questions:
    get:
      tags:
        - questions
      summary: Fetch all questions.
      description: Fetch all questions and their respective answers.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Questions"
  /users/{user_id}/questionnaire_submissions:
    get:
      tags:
        - questionnaire submissions
      summary: Fetch all submissions for a user
      description: Fetch all questionnaire submissions for a given user
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: integer
            minimum: 1
          description: The user ID
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuestionnaireSubmissions"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      tags:
        - questionnaire submissions
      summary: Submit a user questionnaire
      description: Submit a user questionnaire with their answer ids, get a recommended animal in return!
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: integer
            minimum: 1
          description: The user ID
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitQuestionnaire"
        required: true
      responses:
        "201":
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuestionnaireSubmission"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: Invalid or missing answer_ids
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /users/{user_id}/questionnaire_submissions/{id}:
    patch:
      tags:
        - questionnaire submissions
      summary: Save a questionnaire submission
      description: Save a questionnaire submission for a given user
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: integer
            minimum: 1
          description: The user ID
        - in: path
          name: id
          required: true
          schema:
            type: integer
            minimum: 1
          description: The questionnaire submission ID
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SaveQuestionnaire"
        required: true
      responses:
        "200":
          description: Successful save
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuestionnaireSubmission"
        "404":
          description: User or Questionnaire Submission not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: Invalid or missing answer_ids
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /petfinder_animals:
    get:
      tags:
        - petfinder animals
      summary: Fetch animals from Petfinder API
      description: Fetch specific animals from the Petfinder API near the user's zipcode
      parameters:
        - in: query
          name: zipcode
          schema:
            type: string
            examples: [07097]
          required: true
          description: The user's zipcode to login
        - in: query
          name: recommended_animal_id
          schema:
            type: string
            examples: [1]
          required: true
          description: The recommended animal id
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PetfinderAnimals"
        "422":
          description: Invalid or missing zipcode or animal id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    User:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              examples: [user]
            id:
              type: string
              examples: [1]
            attributes:
              type: object
              properties:
                username:
                  type: string
                  examples: [something_unique]
    CreateUser:
      type: object
      properties:
        username:
          type: string
          examples: [something_unique]
    Questions:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Question"
    Question:
      type: object
      properties:
        type:
          type: string
          examples: [question]
        id:
          type: string
          examples: [1]
        attributes:
          type: object
          properties:
            text:
              type: string
              examples: [question?]
            answers:
              type: array
              items:
                $ref: "#/components/schemas/Answer"
    Answer:
      type: object
      properties:
        type:
          type: string
          examples: [answer]
        id:
          type: string
          examples: [1]
        attributes:
          type: object
          properties:
            text:
              type: string
              examples: [answer]
    QuestionnaireSubmissions:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/QuestionnaireSubmission"
    QuestionnaireSubmission:
      type: object
      properties:
        type:
          type: string
          examples: [questionnaire_submission]
        id:
          type: string
          examples: [1]
        attributes:
          type: object
          properties:
            saved:
              type: boolean
              examples: [true, false]
            submission_answers:
              type: array
              items:
                $ref: "#/components/schemas/SubmissionAnswer"
            recommended_animal:
              type: object
              properties:
                type:
                  type: string
                  examples: [recommended_animal]
                id:
                  type: string
                  examples: [1]
                attributes:
                  type: object
                  properties:
                    type:
                      type: string
                      examples: [dachshund]
                    photo_url:
                      type: string
                      examples: [https://photos.com/dachshund]
                    description:
                      type: string
                      examples: [description]
    SubmissionAnswer:
      type: object
      properties:
        type:
          type: string
          examples: [submission_answer]
        id:
          type: string
          examples: [1]
        attributes:
          type: object
          properties:
            text:
              type: string
              examples: [answer]
    RecommendedAnimal:
      type: object
      properties:
        type:
          type: string
          examples: [recommended_animal]
        id:
          type: string
          examples: [1]
        attributes:
          type: object
          properties:
            animal_type:
              type: string
              examples: [dachshund]
            photo_url:
              type: string
              examples: [https://photos.com/dachshund]
            description:
              type: string
              examples: [description]
    PetfinderAnimals:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/PetfinderAnimal"
    PetfinderAnimal:
      type: object
      properties:
        type:
          type: string
          examples: [petfinder_animal]
        id:
          type: string
          examples: [1]
        attributes:
          type: object
          properties:
            name:
              type: string
              examples: [Spot]
            photo_url:
              type: string
              examples:
                [
                  https://photos.petfinder.com/photos/pets/42706540/1/?bust=1546042081,
                ]
            age:
              type: string
              examples: [Young]
            gender:
              type: string
              examples: [Male]
            size:
              type: string
              examples: [Medium]
            species:
              type: string
              examples: [Dog]
            city:
              type: string
              examples: [Jersey City]
            state:
              type: string
              examples: [NJ]
            description:
              type: string
              examples: [Spot is an amazing dog]
            email:
              type: string
              examples: [petfindertechsupport@gmail.com]
    SubmitQuestionnaire:
      type: object
      properties:
        answer_ids:
          type: array
          items:
            type: string
            examples: [[1, 4, 6]]
    SaveQuestionnaire:
      type: object
      properties:
        saved:
          type: boolean
          examples: [true]
    Error:
      type: object
      properties:
        status:
          type: integer
          format: int32
          examples: [422, 400, 404]
        message:
          type: string
      required:
        - status
        - message