openapi_final.yml

openapi: 3.0.3
info:
  title: Marvel Universe API
  version: 1.0.0
  description: 'API for retrieving, creating, updating, and deleting information about the Marvel Universe.'
  x-logo:
    url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Marvel-Comics-Logo.svg/1280px-Marvel-Comics-Logo.svg.png'
servers:
  - url: 'http://localhost:3004/api'
    description: Local
  - url: 'http://localhost:3005'
    description: Mock
  - url: 'https://api-b6feef562ff3.deltablue.io/api'
    description: Production
paths:
  /characters:
    get:
      operationId: getCharacters
      summary: Get all Marvel characters
      description: Retrieve a list of all Marvel characters.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharactersResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Characters
    post:
      operationId: postCharacters
      summary: Create a new Marvel character
      description: Endpoint to create a new Marvel character.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarvelCharacterModel'
            example:
              name: Rocket Raccoon
              first_name: Rocket
              last_name: Raccoon
              description: A member of the Guardians of the Galaxy.
              powers:
                - Engineering genius
                - Expert marksman
                - Strategic thinking
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelCharacterModel'
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Characters
  '/characters/{id}':
    get:
      operationId: getCharacter
      summary: Get a Marvel character
      description: Retrieve information about a specific Marvel character.
      parameters:
        - $ref: '#/components/parameters/CharacterId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelCharacterModel'
        '404':
          description: Marvel character not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Characters
    put:
      operationId: putCharacter
      summary: Update a Marvel character
      description: Update information about a specific Marvel character.
      parameters:
        - $ref: '#/components/parameters/CharacterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarvelCharacterModel'
            example:
              name: Rocket Raccoon
              first_name: Rocket
              last_name: Raccoon
              description: A genetically modified raccoon with a knack for engineering and firearms. A member of the Guardians of the Galaxy.
              powers:
                - Engineering genius
                - Expert marksman
                - Strategic thinking
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelCharacterModel'
        '404':
          description: Marvel character not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Characters
    delete:
      operationId: deleteCharacter
      summary: Delete a Marvel character
      description: Delete a specific Marvel character.
      parameters:
        - $ref: '#/components/parameters/CharacterId'
      responses:
        '204':
          description: Successfully deleted
        '404':
          description: Marvel character not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Characters
  /teams:
    get:
      operationId: getTeams
      summary: Get all Marvel teams
      description: Retrieve a list of all Marvel teams.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsResponse'
      tags:
        - Teams
    post:
      operationId: postTeams
      summary: Create a new Marvel team
      description: Endpoint to create a new Marvel team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarvelTeamModel'
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelTeamModel'
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Teams
  '/teams/{id}':
    get:
      operationId: getTeam
      summary: Get a Marvel team
      description: Retrieve information about a specific Marvel team.
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelTeamModel'
        '404':
          description: Marvel team not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Teams
    put:
      operationId: putTeam
      summary: Update a Marvel team
      description: Update information about a specific Marvel team.
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarvelTeamModel'
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelCharacterModel'
        '404':
          description: Marvel team not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Teams
    delete:
      operationId: deleteTeam
      summary: Delete a Marvel team
      description: Delete a specific Marvel team.
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '204':
          description: Successfully deleted
        '404':
          description: Marvel team not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Teams
  /movies:
    get:
      operationId: getMovies
      summary: Get all Marvel movies
      description: Retrieve a list of all Marvel movies.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoviesResponse'
      tags:
        - Movies
    post:
      operationId: postMovies
      summary: Create a new Marvel movie
      description: Endpoint to create a new Marvel movie.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarvelMovieModel'
            example:
              title: Spider-man Across the Spider-Verse
              release_date: 2023-06-02
              description: Miles Morales is back in the Spider-Verse, and things are going to get even stranger with a face-to-face encounter from the Spider Society.
              director: Joaquim Dos Santos
              rank: 3
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelMovieModel'
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Movies
  '/movies/{id}':
    get:
      operationId: getMovie
      summary: Get a Marvel movie
      description: Retrieve information about a specific Marvel movie.
      parameters:
        - $ref: '#/components/parameters/MovieId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelMovieModel'
        '404':
          description: Marvel movie not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Movies
    put:
      operationId: putMovie
      summary: Update a Marvel movie
      description: Update information about a specific Marvel movie.
      parameters:
        - $ref: '#/components/parameters/MovieId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarvelMovieModel'
            example:
              title: 'Spider-man: Across the Spider-Verse'
              release_date: 2023-06-02
              description: Miles Morales is back in the Spider-Verse, and things are going to get even stranger with a face-to-face encounter from the Spider Society.
              director: Joaquim Dos Santos
              rank: 3
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarvelMovieModel'
        '404':
          description: Marvel movie not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityError'
      tags:
        - Movies
    delete:
      operationId: deleteMovie
      summary: Delete a Marvel movie
      description: Delete a specific Marvel movie.
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '204':
          description: Successfully deleted
        '404':
          description: Marvel movie not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Movies
components:
  parameters:
    CharacterId:
      name: id
      in: path
      required: true
      description: ID of the Marvel character
      schema:
        type: integer
      example: 1
    TeamId:
      name: id
      in: path
      required: true
      description: ID of the Marvel team
      schema:
        type: integer
      example: 1
    MovieId:
      name: id
      in: path
      required: true
      description: ID of the Marvel movie
      schema:
        type: integer
      example: 1
    LimitParam:
      name: limit
      in: query
      description: The number of items to return per page.
      required: false
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
    PageParam:
      name: page
      in: query
      description: The page number for pagination.
      required: false
      schema:
        type: integer
        default: 1
  schemas:
    MarvelCharacterModel:
      description: A Marvel character.
      type: object
      properties:
        id:
          description: ID of the Marvel character
          type: integer
          format: int64
          example: 7
          readOnly: true
        name:
          description: The full name of the Marvel character.
          type: string
          example: Iron Man
        first_name:
          description: The first name of the Marvel character.
          type: string
          example: Tony
        last_name:
          description: The last name of the Marvel character.
          type: string
          example: Stark
        description:
          description: A brief description of the Marvel character.
          type: string
          example: 'Genius, billionaire, playboy, philanthropist.'
          nullable: true
        powers:
          description: List of superpowers possessed by the Marvel character.
          type: array
          items:
            type: string
          example:
            - Superhuman strength
            - Powered armor suit
            - Genius-level intellect
      additionalProperties: false
      required:
        - name
    MarvelTeamModel:
      description: A Marvel team.
      type: object
      properties:
        id:
          description: ID of the Marvel team
          type: integer
          format: int64
          example: 1
          readOnly: true
        name:
          description: The full name of the Marvel character.
          type: string
          example: Iron Man
        description:
          description: A brief description of the Marvel character.
          type: string
          example: 'Genius, billionaire, playboy, philanthropist.'
          nullable: true
      additionalProperties: false
      required:
        - name
        - description
    MarvelMovieModel:
      description: A Marvel movie.
      type: object
      properties:
        id:
          description: ID of the Marvel movie
          type: integer
          format: int64
          example: 1
          readOnly: true
        title:
          description: The title of the Marvel movie.
          type: string
          example: Iron Man
        release_date:
          description: The release date of the Marvel movie.
          type: string
          format: date
          example: 2008-05-02
        director:
          description: The director of the Marvel movie.
          type: string
          example: Jon Favreau
        description:
          description: A brief description of the Marvel movie.
          type: string
          example: "A wealthy industrialist builds a powered exoskeleton and becomes the technologically advanced superhero Iron Man."
          nullable: true
        rank:
          description: The ranking of the Marvel movie.
          type: number
          example: 1
      additionalProperties: false
      required:
        - title
        - description
    CharactersResponse:
      type: object
      properties:
        characters:
          description: List of Marvel characters.
          type: array
          items:
            $ref: '#/components/schemas/MarvelCharacterModel'
          example:
            - id: 1
              name: Iron Man
              first_name: Tony
              last_name: Stark
              description: 'Genius, billionaire, playboy, philanthropist.'
              powers:
                - Superhuman strength
                - Powered armor suit
                - Genius-level intellect
            - id: 2
              name: Spider-Man
              first_name: Peter
              last_name: Parker
              description: Friendly neighborhood superhero.
              powers:
                - Wall-crawling
                - Spider-sense
                - Web-shooters
        pagination:
          $ref: '#/components/schemas/PaginationModel'
    TeamsResponse:
      type: object
      properties:
        teams:
          description: List of Marvel teams.
          type: array
          items:
            $ref: '#/components/schemas/MarvelTeamModel'
        pagination:
          $ref: '#/components/schemas/PaginationModel'
    MoviesResponse:
      type: object
      properties:
        movies:
          description: List of Marvel movies.
          type: array
          items:
            $ref: '#/components/schemas/MarvelMovieModel'
        pagination:
          $ref: '#/components/schemas/PaginationModel'
    PaginationModel:
      description: Pagination information.
      type: object
      properties:
        pagination:
          type: object
          properties:
            total:
              description: The total number of items for the requested resource.
              type: integer
              example: 100
            current_page:
              description: The current page number.
              type: integer
              example: 1
            next_page:
              description: The next page number. Null if there is no next page.
              type: integer
              example: 2
              nullable: true
            prev_page:
              description: The previous page number. Null if there is no previous page.
              type: integer
              example: null
              nullable: true
            per_page:
              description: The number of items to return per page.
              type: integer
              example: 10
            total_pages:
              description: The total number of pages.
              type: integer
              example: 10
    UnprocessableEntityError:
      type: object
      properties:
        error:
          description: Description of the error.
          type: string
        details:
          description: An array of objects providing details about the validation errors encountered in the request.
          type: array
          items:
            type: object
            properties:
              field:
                description: The field causing the validation error.
                type: string
              message:
                description: Details about the validation error.
                type: string
      example:
        error: Validation errors
        details:
          - field: first_name
            message: Field 'first_name' must be of type 'String'.
    BadRequestError:
      type: object
      properties:
        error:
          description: Description of the error.
          type: string
      example:
        error: Page number cannot be greater than total number of pages
    NotFoundError:
      type: object
      properties:
        error:
          description: Description of the error.
          type: string
      example:
        error: Marvel character not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []
tags:
  - name: Characters
    description: Manage all Marvel characters.
  - name: Teams
    description: Manage all teams from the Marvel Universe.
    x-exclude: true
  - name: Movies
    description: Manage all movies from the Marvel Universe.
    x-exclude: true