editor.swagger.io.yaml

openapi: 3.0.0
info:
  description: Routes
  version: 1.0.0
  title: Rails Boilerplate
  contact:
    email: from@example.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/nickeryno/Rails Boilerplate/1.0.0
tags:
  - name: Auth
    description: Authentication
  - name: Users
    description: User management and retrieval
  - name: Questions
    description: Question management and retrieval
paths:
  /auth/register:
    post:
      summary: Register as user
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                  description: must be unique
                password:
                  type: string
                  format: password
                  minLength: 8
                  description: At least one number and one letter
              example:
                name: fake name
                email: fake@example.com
                password: password1
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  tokens:
                    $ref: '#/components/schemas/AuthTokens'
        '400':
          $ref: '#/components/responses/DuplicateEmail'
  /auth/login:
    post:
      summary: Login
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
              example:
                email: fake@example.com
                password: password1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  tokens:
                    $ref: '#/components/schemas/AuthTokens'
        '401':
          description: Invalid email or password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 401
                message': Invalid email or password
  /auth/logout:
    post:
      summary: Logout,
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
              properties:
                refreshToken:
                  type: string
              example:
                refreshToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZWJhYzUzNDk1NGI1NDEzOTgwNmMxMTIiLCJpYXQiOjE1ODkyOTg0ODQsImV4cCI6MTU4OTMwMDI4NH0.m1U63blB0MLej_WfB7yC2FTMnCziif9X8yzwDEfJXAg
      responses:
        '204':
          description: No content
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/refresh-tokens:
    post:
      summary: Refresh auth tokens
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
              properties:
                refreshToken:
                  type: string
              example:
                refreshToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZWJhYzUzNDk1NGI1NDEzOTgwNmMxMTIiLCJpYXQiOjE1ODkyOTg0ODQsImV4cCI6MTU4OTMwMDI4NH0.m1U63blB0MLej_WfB7yC2FTMnCziif9X8yzwDEfJXAg
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokens'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/forgot-password:
    post:
      summary: Forgot password
      description: An email will be sent to reset password.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
              example:
                email: fake@example.com'
      responses:
        '204':
          description: No content'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/reset-password:
    post:
      summary: Reset password
      tags:
        - Auth
      parameters:
        - in: query
          name: token,
          required: true
          schema:
            type: string
          description: The reset password token'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - password
              properties:
                password:
                  type: string
                  format: password
                  minLength: 8
                  description: At least one number and one letter
              example:
                password: password1
      responses:
        '204':
          description: No content
        '401':
          description: Password reset failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 401
                message': Password reset failed'
  /auth/send-verification-email:
    post:
      summary: Send verification email
      description: An email will be sent to verify email.
      tags:
        - Auth
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No content'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/verify-email:
    post:
      summary: verify email
      tags:
        - Auth
      parameters:
        - in: query
          name: token,
          required: true
          schema:
            type: string
          description: The verify email token'
      responses:
        '204':
          description: No content'
        '401':
          description: verify email failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 401
                message': verify email failed'
  /users:
    post:
      summary: Create a user
      description: Only admins can create other users.
      tags:
        - Users
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
                - role
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                  description: must be unique
                password:
                  type: string
                  format: password
                  minLength: 8
                  description: At least one number and one letter
                role:
                  type: string
                  enum:
                    - user
                    - admin
              example:
                name: fake name
                email: fake@example.com
                password: password1
                role: user
      responses:
        '201':
          description: Created,
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/DuplicateEmail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      summary: Get all users
      description: Only admins can retrieve all users.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: User name
        - in: query
          name: role
          schema:
            type: string
          description: User role
        - in: query
          name: sortBy
          schema:
            type: string
          description: sort by query in the form of field:desc/asc (ex. name:asc)
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Maximum number of users
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  page:
                    type: integer
                    example: 1
                  limit:
                    type: integer
                    example: 10
                  totalPages:
                    type: integer
                    example: 1
                  totalResults:
                    type: integer
                    example: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /users/{id}:
    get:
      summary: Get a user
      description: Logged in users can fetch only their own user information. Only admins can fetch other users.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update a user
      description: Logged in users can only update their own information. Only admins can update other users.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                  description: must be unique
                password:
                  type: string
                  format: password
                  minLength: 8
                  description: At least one number and one letter
              example:
                name: fake name
                email: fake@example.com
                password: password1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/DuplicateEmail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete a user
      description: Logged in users can delete only themselves. Only admins can delete other users.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User id
      responses:
        '200':
          description: No content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /questions/{id}:
    get:
      summary: Get a question
      description: Logged in users can fetch only their own questions information. Only admins can fetch other questions.
      tags:
        - Questions
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Question id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Question'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
        role:
          type: string
          enum:
            - user
            - admin
      example:
        id: 5ebac534954b54139806c112,
        email: fake@example.com
        name: fake name
        role: user
    Token:
      type: object
      properties:
        Token:
          type: string
        expires:
          type: string
          format: date-time
      example:
        token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZWJhYzUzNDk1NGI1NDEzOTgwNmMxMTIiLCJpYXQiOjE1ODkyOTg0ODQsImV4cCI6MTU4OTMwMDI4NH0.m1U63blB0MLej_WfB7yC2FTMnCziif9X8yzwDEfJXAg,
        expires: 2020-05-12T16:18:04.793Z'
    AuthTokens:
      type: object
      properties:
        access:
          $ref: '#/components/schemas/Token'
        refresh:
          $ref: '#/components/schemas/Token'
    Error:
      type: object
      properties:
        code:
          type: number
        message:
          type: string
    Question:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          example: 'Which language is used for web apps?'
        manufacturer:
          $ref: '#/components/schemas/Answer'
    Answer:
      required:
        - text
      properties:
        text:
          type: string
          example: 'Python'
        flag:
          type: boolean
          example: 'true'
        phone:
          type: string
          example: 408-867-5309
      type: object
  responses:
    DuplicateEmail:
      description: Email already taken,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400,
            message': Email already taken'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message': Please authenticate
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403,
            message': Forbidden
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message': Not found'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT