swagger.yml

---
swagger: '2.0'
info:
  version: 1.0.0
  title: ubike-service
  description: |
    #### An application server for Taipei YouBike related service.
basePath: "/"
paths:
  /v1/ubike-station/taipei:
    get:
      tags:
        - v1
      summary: Find 2 nearest ubike station
      description: Return a list of 2 nearest ubike station based on latitude and longitude in request parameters.
      operationId: find2Nearest
      parameters:
        - in: query
          name: lat
          description: "latitude (-180° ~ 180°)"
          required: true
          type: number
          minimum: -180
          maximum: 180
        - in: query
          name: lng
          description: "longitude (-180° ~ 180°)"
          required: true
          type: number
          minimum: -180
          maximum: 180
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              code:
                type: integer
                description: "<br>1: all ubike stations are full<br> 0: OK<br> -1: invalid latitude or longitude<br> -2: given location not in Taipei City<br> -3: system error"
                example: 0
              result:
                description: "<br>exceptions: <br>1. empty while code is not zero.<br> 2. skip stations with no ubike left."
                type: array
                items:
                  type: object
                  properties:
                    station:
                      type: string
                    num_ubike:
                      type: integer
                example:
                  - station: 捷運象山站
                    num_ubike: 10
                  - station: 世貿二館
                    num_ubike: 33
        500:
          description: Server Internal Error
      produces:
        - application/json