openapi.yml

openapi: 3.0.3

info:
  version: 0.0.1
  title: 'Contacts API REST'
  description: Contacts API for management a Contact List
  termsOfService: https://swagger.io/terms/
  license:
    name: MIT
    url: LICENCE

tags:
  - name: Contacts
    description: Everything about Contacts

servers:
  - url: http://localhost:8080/
    description: 'DEV: Please configure according to your local environment.'

paths:
  /contacts:
    get:
      tags:
        - Contacts
      summary: Get all contacts
      responses:
        200:
          description: A JSON array of contacts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
        404:
          description: Endpoint no found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - Contacts
      summary: Create a new contact
      responses:
        201:
          description: Created
        400:
          description: Bad request. Contact ID must be an integer and larger than 0.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /contacts/{id}:
    parameters:
      - name: id
        description: The unique identifier of the contact
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ContactId'
    get:
      tags:
        - Contacts
      summary: Get a contact
      responses:
        200:
          description: A new contact have been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        404:
          description: No contact found for the provided `contactId`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ContactId:
      description: The unique identifier of a contact
    Contact:
      type: object
      properties:
        id:
          type: integer
        firstname:
          type: string
        lastname:
          type: string
        phone:
          type: string
      required:
        - id
        - firstname
        - phone
    ApiResponse:
      type: object
      properties:

    Info:
      type: object
      properties:
        count:
          type: integer
          description: The length of the response
        pages:
          type: integer
          description: Link to the next page (if it exists)
        next:
          type: string
          description: Link to the next page of resources
        prev:
          type: string
          description: Link to the previous page (if it exists)
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: An error code of business
        message:
          type: string
          description: A human-readable error message
      required:
        - code
        - message