api.core.swagger.io

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: ...DRAFT... Ricardo REST API
  description: Biggest e-commerce provider in Switzerland's API - Web friendly
  version: "0.1.0"
# the domain of the service
host: api.ricardo.ch
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /
produces:
  - application/json
paths:
  /search:
    get:
      summary: Get a collection of articles matching the querystrings
      description: Hello Fred, this is for you
      parameters:
        - name: query
          in: query
          description: The search terms to query for
          type: number
        - name: per_page
          in: query
          description: Items per page to retrieve
          type: number
        - name: page
          in: query
          description: The page you want to retrieve
          type: number
      responses:
        200:
          description: An array of articles matching the queries
          schema:
            type: array
            items:
              $ref: '#/definitions/ArticleCompact'
              
  /article/{id}:
    get:
      summary: A single, detailed article representation
      parameters:
        - name: id
          in: path
          description: The article id to fetch details for
          required: true
          type: number
      responses:
        200:
          description: A detailed article representation
          schema:
            $ref: '#/definitions/ArticleDetailed'
  
  /transaction/bid:
    post:
      summary: Perform a bid transaction
      parameters:
        - name: transaction
          in: body
          description: An object containing bid transaction infos
          schema:
            $ref: '#/definitions/BidTransaction'
      responses:
        200:
          description: Ok
          
  /transaction/buy:
    post:
      summary: Perform a buy transaction
      parameters:
        - name: transaction
          in: body
          description: An object containing buy transaction infos
          schema:
            $ref: '#/definitions/BuyTransaction'
      responses:
        200:
          description: Confirmation
  
  /user:
    get:
      summary: Information about an authenticated user
      responses:
        200:
          description: Ok
          schema:
            $ref: '#/definitions/AuthenticatedUser'
  
  /oauth/token:
    post:
      summary: "Adhering to Openid Connect Spec. Using Implicit or Password grant type flows"
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: grant_type
          in: formData
          required: true
          type: string
          enum:
            - password
        - name: username
          in: formData
          required: true
          type: string
        - name: password
          in: formData
          required: true
          type: string
        - name: client_id
          in: formData
          required: true
          type: string
      responses:
        200:
          description: Ok
          schema:
            type: object
            properties:
              access_token: 
                type: string
                description: the jwt token
              token_type: 
                type: string
                description: the type of token (ex. Bearer)
              expires_in: 
                type: number
                description: number of seconds until the token expires
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                  - invalid_request
                  - invalid_client
                  - invalid_grant
                  - unauthorized_client
                  - unsupported_grant_type
      
  /login/session/{token}:
    get:
      summary: Get the single sign on cookie for a user token
      parameters:
        - name: token
          in: path
          required: true
          description: The authenticated token you already got for the user
          type: string
      responses:
        200:
          description: Set cookie response
          headers:
            Set-Cookie:
              type: string
              description: The Auto-Login cookie to set on the client

  /login/session:
    post:
      summary: Get user token for a single sign on cookie
      parameters:
        - name: session_infos
          in: body
          description: | 
            The session_guid from a cookie for an already authenticated user
          schema:
            type: object
            properties:
              session_guid:
                type: string
      responses:
        200:
          description: Ok
    
definitions:
  ArticleCompact:
    type: object
    properties:
      article_id:
        type: number
      category_id:
        type: number
      buynow_price:
        type: number
      bids_count:
        type: string
      image:
        type: string
      is_auction: 
        type: boolean
      is_classified:
        type: boolean
      is_buynow:
        type: boolean
      end_date:
        type: string
        format: date
      delta_t:
        type: string
        format: date
      shipping_cost:
        type: number
      shipping_condition:
        type: string
      title:
        type: string
      sub_title:
        type: string
      is_premium:
        type: string
      condition:
        type: string
      seller_id:
        type: number
      quantity:
        type: number
      
        
  ArticleDetailed:
    allOf: 
      - $ref: "#/definitions/ArticleCompact"
      - type: object
        properties:
          pictures:
            type: array
            items:
              type: string
          total_price: 
            type: number
          available_quantity:
            type: number
          payment_methods:
            type: array
            items:
              type: object
              properties:
                id:
                  type: number
                text:
                  type: string
          seller:
            type: object
            properties:
              schema:
                $ref: '#/definitions/UserPublic'
  
  BidTransaction:
    type: object
    properties:
      article_id:
        type: number
      bidder_id:
        type: number
      bid_price:
        type: number

  BuyTransaction:
    type: object
    properties:
      article_id:
        type: number
      quantity:
        type: number
      buyer_id:
        type: number

  AuthenticatedUser:
    type: object
    properties:
      id:
        type: number
      addresses:
        type: array
        items:
          $ref: '#/definitions/Address'
      firstname:
        type: string
      lastname:
        type: string
      nickname:
        type: string
      mobile:
        type: string
      phone:
        type: string
      email:
        type: string

  Address:
    type: object
    properties:
      address1:
        type: string
      address2:
        type: string
      streetnumber:
        type: string
      postalbox:
        type: string
      zipcode:
        type: string
      city:
        type: string
      country:
        type: string

  UserPublic:
    type: object
    properties:
      id:
        type: number
      canton:
        type: string
      nickname:
        type: string
      zipcode:
        type: number
      city:
        type: string