swagger.yaml

swagger: '2.0'
info:
  description: Documentation for `api.train.cat`
  version: 2.0.0
  title: API train-cat
host: api.train.cat
tags:
  - name: station
  - name: stop_time
  - name: trip
  - name: user
  - name: action
  - name: alert
schemes:
  - https
paths:
  /stations:
    get:
      tags:
        - station
      summary: List all stations
      operationId: cget_stations
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: query
          type: integer
          name: _page
          description: Current page
          default: 1
          required: false
        - in: query
          type: integer
          name: _max_per_page
          description: Max result per page
          default: 20
          minimum: 1
          maximum: 100
          required: false
        - in: query
          type: string
          name: name
          description: Search by name
          required: false
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/Collection'
        '400':
          description: Something is wrong with the filters
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Page not found
          schema:
            $ref: '#/definitions/Error'
  '/stations/{station_id}':
    get:
      tags:
        - station
      summary: Retrieve a station
      operationId: get_stations
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: path
          type: integer
          name: station_id
          description: Unique identifier of the station
          required: true
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/Station'
        '404':
          description: Resource Not Found
          schema:
            $ref: '#/definitions/Error'
  '/stations/{station_id}/stops_time':
    get:
      tags:
        - stop_time
      summary: List all stops time for one station
      operationId: cget_station_stops_time
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: path
          type: integer
          name: station_id
          description: Unique identifier of the station
          required: true
        - in: query
          type: integer
          name: _page
          description: Current page
          default: 1
          required: false
        - in: query
          type: integer
          name: _max_per_page
          description: Max result per page
          default: 20
          minimum: 1
          maximum: 100
          required: false
        - in: query
          type: string
          name: mission
          description: Search by mission
          required: false
        - in: query
          type: string
          name: train_through_station_id
          description: Search by train through a specific station ID
          required: false
        - in: query
          type: string
          name: scheduled_before
          description: Search by schedule
          required: false
        - in: query
          type: string
          name: scheduled_after
          description: Search by schedule
          required: false
        - in: query
          type: string
          name: scheduled_at
          description: Search by schedule
          required: false
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Collection'
        '400':
          description: something goes wrong with the filters
        '404':
          description: Station Not Found
  '/stations/{station_id}/stops_time/{stop_time_id}/alerts':
    post:
      tags:
        - alert
      summary: Create new alert for one stop time
      operationId: post_alert
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: path
          type: integer
          name: station_id
          description: Unique identifier of the station
          required: true
        - in: path
          type: integer
          name: stop_time_id
          description: ID of the stop_time
          required: true
        - in: body
          name: stop
          schema:
            $ref: '#/definitions/AlertInput'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Alert'
        '400':
          description: Something is wrong with the value
        '401':
          description: You should be authentified
        '403':
          description: You have not the permission
  '/trips/{trip_id}':
    get:
      tags:
        - trip
      summary: Retrieve a trip
      operationId: get_trip
      produces:
        - application/json
      parameters:
        - in: path
          type: integer
          name: trip_id
          description: Unique id of the trip
          required: true
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/Trip'
        '404':
          description: resource not found
          schema:
            $ref: '#/definitions/Error'
  '/trips/{trip_id}/terminus':
    get:
      tags:
        - trip
      summary: Retrieve terminus from a trip
      operationId: get_terminus
      produces:
        - application/json
      parameters:
        - in: path
          type: integer
          name: trip_id
          description: Unique id of the trip
          required: true
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definition/Station'
        '404':
          description: resource not found
          schema:
            $ref: '#definition/Error'
  /users:
    post:
      tags:
        - user
      summary: Create new user
      operationId: post_user
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: body
          name: user
          schema:
            $ref: '#/definitions/UserInput'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/User'
        '400':
          description: Something is wrong with the value
  /login:
    post:
      tags:
        - user
      summary: Login user
      operationId: login
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: body
          name: user
          schema:
            $ref: '#/definitions/UserToken'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Token'
        '400':
          description: Bad Credentials
  /actions:
    post:
      tags:
        - action
      summary: Create method for be notified
      operationId: post_action
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: header
          description: Token of the user
          type: string
          name: Authoriration
          default: Bearer <token>
        - in: body
          name: action
          schema:
            $ref: '#/definitions/ActionInput'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/Action'
        '400':
          description: Something is wrong with the value
        '401':
          description: You should be authentified
        '403':
          description: You have not the permission
  /alerts:
    get:
      tags:
        - alert
      summary: List all alerts
      operationId: cget_alerts
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          description: Format response (only application/json is accepted)
          type: string
          name: Accept
          default: application/json
        - in: query
          type: integer
          name: _page
          description: Current page
          default: 1
          required: false
        - in: query
          type: integer
          name: _max_per_page
          description: Max result per page
          default: 20
          minimum: 1
          maximum: 100
          required: false
        - in: query
          type: string
          name: code_train
          description: Search by code train
          required: false
        - in: query
          type: string
          name: station_id
          description: Search by station id
          required: false
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/Collection'
        '400':
          description: Something is wrong with the filters
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Page not found
          schema:
            $ref: '#/definitions/Error'
definitions:
  Collection:
    type: object
    properties:
      page:
        type: integer
        format: int
      pages:
        type: integer
        format: int
      limit:
        type: integer
        format: int
      total:
        type: integer
        format: int
      _embedded:
        type: object
        properties:
          items:
            type: array
            items:
              type: object
              description: Collection of entity
  Link:
    type: object
    properties:
      href:
        type: string
  Station:
    type: object
    properties:
      id:
        type: integer
        format: int
      name:
        type: string
      _links:
        type: object
        properties:
          self:
            $ref: '#/definitions/Link'
          stop:
            $ref: '#/definitions/Link'
  StationInput:
    type: object
    properties:
      name:
        type: string
        description: Station name
        minLength: 2
        maxLength: 255
      uic:
        description: Code UIC for the station
        type: string
        minLength: 8
        maxLength: 8
      is_enable:
        description: If the station is enable for realtime API
        type: boolean
  Trip:
    type: object
    properties:
      id:
        type: integer
        description: ID of the trip
      code:
        type: string
        description: Unique code of the train
      mission:
        type: string
        description: Mission of the train (4 letters)
      _links:
        type: object
        properties:
          self:
            $ref: '#/definitions/Link'
      _embedded:
        type: object
        properties:
          terminus:
            $ref: '#/definitions/Station'
  StopTime:
    type: object
    properties:
      id:
        type: integer
      schedule:
        type: string
        description: 'hh:mm of the stop'
      _embedded:
        type: object
        properties:
          mission:
            type: string
          days:
            type: number
  User:
    type: object
    properties:
      id:
        type: integer
      username:
        type: string
      email:
        type: string
      roles:
        type: array
        items:
          type: string
  UserInput:
    type: object
    properties:
      username:
        type: string
        minLength: 2
        maxLength: 255
      email:
        type: string
        maxLength: 255
      password:
        type: string
        minLength: 6
        maxLength: 255
  UserToken:
    type: object
    properties:
      username:
        type: string
      password:
        type: string
  Token:
    type: object
    properties:
      token:
        type: string
  Action:
    type: object
    properties:
      id:
        type: integer
      type:
        type: string
        pattern: (messenger|telegram)
      data:
        type: object
      _links:
        type: object
        properties:
          self:
            $ref: '#/definitions/Link'
  ActionInput:
    type: object
    properties:
      type:
        type: string
        pattern: (messenger|telegram)
      data:
        type: object
  Alert:
    type: object
    properties:
      id:
        type: integer
      action_id:
        type: integer
      _embedded:
        type: object
        properties:
          action:
            $ref: '#/definitions/Action'
          station:
            $ref: '#/definitions/Station'
      _links:
        type: object
        properties:
          self:
            $ref: '#/definitions/Link'
          train:
            $ref: '#/definitions/Link'
  AlertInput:
    type: object
    properties:
      action_id:
        type: integer
  Error:
    type: object
    properties:
      error:
        type: string