api.doc.yaml

openapi: 3.0.0
info:
  title: Genemitter API
  description: Optional multiline or single-line description in HTML.
  version: 0.0.1
servers:
  - url: 'http://test-api.genemitter.snio.dev'
    description: Genemitter Test Environment
paths:
  /users:
    post:
      tags:
        - Users
      summary: Sign up/register a new user
      description: This resouce is able to sign up/register a new user in the database.
      operationId: createUser
      parameters:
        - name: Accept
          description: application/json
          in: header
          required: true
          schema:
            type: string
        - name: Content-Type
          description: application/json
          in: header
          required: true
          schema:
            type: string
      requestBody:
        description: A JSON object containing user essential data
        required: true
        content:
          application/json:
            schema:
              required:
                - name
                - email
                - password
              type: object
              properties:
                name:
                  type: string
                  description: User's full name
                  minLength: 5
                  maxLength: 65
                email:
                  type: string
                  description: The e-mail that will uniquely identify the user on the system and become its login credential
                  format: email
                password:
                  type: string
                  description: User's password
                  format: password
                  minLength: 12
                  maxLength: 50
      responses:
        '201':
          description: Created
        '422':
          description: Unprocessable Entity / Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The main exception raised by the server
                    example: The given data was invalid.
                  errors:
                    type: array
                    description: Optional error object containing details of the server error
                    properties:
                      field_name:
                        type: array
                        description: Error message specific to each field included in the error object
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                              description: Field name and respective error message
                              example: name
                    example:
                      name: The field 'name' is required
                      email: The field 'e-mail' is not of the expected type
  '/users/{user_id}':
    get:
      tags:
        - Users
      summary: Get a user by ID
      description: This resource is able to retrieve a registered use by its ID.
      operationId: getUser
      parameters:
        - $ref: '#/paths/~1users/post/parameters/0'
        - name: Authorization
          description: 'Bearer {{access_token}}'
          in: header
          required: true
          schema:
            type: string
        - $ref: '#/paths/~1users/post/parameters/1'
        - in: path
          name: user_id
          description: Numeric ID of the user to be retrieved
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The ID of the given user
                    example: 128
                  name:
                    type: string
                    description: User's full name
                    minLength: 5
                    maxLength: 60
                  email:
                    type: string
                    format: email
                    description: The e-mail that will uniquely identify the user on the system and become its login credential
                  created_at:
                    type: string
                    description: The date and time when the record was created
                    format: date-time
                    example: 2021-04-11T15:50:48.000Z
                  updated_at:
                    type: string
                    description: The date and time when the record was last updated
                    format: date-time
                    example: 2021-05-12T13:52:04.000Z
                required:
                  - id
                  - name
                  - email
        '403':
          description: Forbidden / Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/paths/~1users/post/responses/422/content/application~1json/schema'
        '404':
          description: The specified resource was not found
tags:
  - name: Users