Swagger examples

shorty.yml

swagger: '2.0'
info:
  title: URL Shortener service API
  description: Shorten your URL on the fly
  version: "1.0.0"
host: shorty-url-shortener.herokuapp.com
schemes:
  - http
basePath: /
consumes:
  - application/json
produces:
  - application/json
paths:
  /shorten:
    post:
      summary: Generates shortcode for presented URL
      parameters:
        - name: url
          in: body
          description: URL to shorten
          required: true
          schema:
            $ref: '#/definitions/URL'
      responses:
        201:
          description: "A random shortcode is generated if none is requested, the generated short code has exactly 6 alpahnumeric characters and passes the following regexp: ^[0-9a-zA-Z_]{6}$."
          schema:
            $ref: '#/definitions/Shortcode'
        400:
          description: url is not present
        409:
          description: The the desired shortcode is already in use. Shortcodes are case-sensitive.
        422:
          description: "The shortcode fails to meet the following regexp: ^[0-9a-zA-Z_]{6}$."
  /{shortcode}:
    get:
      summary: Get url by shortcode
      parameters:
        - name: shortcode
          in: path
          required: true
          type: string
      responses:
        302:
          description: response with the location header pointing to the shortened URL
          headers:
            Location:
              description: shortened URL
              type: string
        404:
          description: The shortcode cannot be found in the system
  '/{shortcode}/stats':
    get:
      summary: Get statistics on shortcode
      parameters:
        - name: shortcode
          in: path
          required: true
          type: string
      responses:
        200:
          description: Shortcode statistics
          schema:
            $ref: '#/definitions/ShortcodeStats'
        404:
          description: The shortcode cannot be found in the system

definitions:
  URL:
    type: object
    properties:
      url:
        type: string
        description: url to shorten
      shortcode:
        type: string
        description: preferential shortcode
    required:
      - url
  Shortcode:
    type: object
    properties:
      shortcode:
        type: string
        description: url encoded shortcode
  ShortcodeStats:
    type: object
    properties:
      startDate:
        type: string
        format: date-time
        description: date when the url was encoded, conformant to ISO8601
      redirectCount:
        type: integer
        description: number of times the endpoint GET /shortcode was called
      lastSeenDate:
        type: string
        format: date-time
        description: date of the last time the a redirect was issued, not present if redirectCount == 0