hebcal-swagger.yml

# Example YAML to get you started quickly.
# Be aware that YAML has indentation based scoping.
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "1.0.0"
  title: Hebcal API
  description: Description something something
  license:  
    name: Creative Commons Attribution 3.0 License
    url: "http://creativecommons.org/licenses/by/3.0/deed.en_US"
  contact:
    name: Hebcal
    url: "https://www.hebcal.com/home/about"

host: www.hebcal.com

schemes:
  - http

# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /converter:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: |
        A simple API for converting between Gregorian and Hebrew dates. Two output formats are supported: **JSON** and **XML**. If none of the triplets (`gy`, `gm`, `gd`) or (`hy`, `hm`, `hd`) is completely specified, the API ignores those parameters and returns the current date.
      produces:
        - application/json
        - application/xml

      # This is array of GET operation parameters:
      parameters:
        # An example parameter that is in query and is required
        - name: cfg
          in: query
          description: Output, in `json` or `xml`
          required: true
          type: string
          format: "json|xml"
        - name: g2h
          in: query
          description: Convert from Gregorian to Hebrew date
          required: false
          allowEmptyValue: true
          type: integer
          format: 0 | 1
          minimum: 0
          maximum: 1
        - name: h2g
          in: query
          description: Convert from Hebrew to Gregorian date
          required: false
          allowEmptyValue: true
          type: integer
          format: 0 | 1
          minimum: 0
          maximum: 1
        - name: gy
          in: query
          description: Gregorian year.
          required: false
          allowEmptyValue: true
          type: integer
          format: int32
          minimum: 0
        - name: gm
          in: query
          description: "Gregorian month"
          required: false
          type: integer
          format: 1...12
          minimum: 1
          maximum: 12
        - name: gd
          in: query
          description: Gregorian day of month
          required: false
          allowEmptyValue: true
          type: integer
          format: 1...31
          minimum: 1
          maximum: 31
        - name: gs
          in: query
          description: After sunset on Gregorian date
          required: false
          allowEmptyValue: true
          type: string
          format: on|off
          default: off
        - name: hy
          in: query
          description: Hebrew year
          required: false
          allowEmptyValue: true
          type: integer
          format: int32
          minimum: 0
        - name: hm
          in: query
          description: Hebrew month
          required: false
          allowEmptyValue: true
          type: string
          format: Nisan | Iyyar | Sivan | Tamuz | Av | Elul | Tishrei | Cheshvan | Kislev | Tevet | Shvat | Adar1 | Adar2
        - name: hd
          in: query
          description: Hebrew day of month
          required: false
          allowEmptyValue: true
          type: integer
          format: 1...30
          minimum: 1
          maximum: 30
        - name: callback
          in: query
          description: Wraps the JSON output text in parentheses and a function name of your choosing.
          required: false
          allowEmptyValue: true
          type: string
          format: "A-Z a-z 0-9 . _"

      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            $ref: '#/definitions/Date'
          examples: 
            application/json:
              {
                "gy": 2011,
                "gm": 6,
                "gd": 2,
                "hy": 5771,
                "hm": "Iyyar",
                "hd": 29,
                "hebrew": "כ״ט בְּאִיָיר תשע״א",
                "events": [
                  "Parashat Nasso",
                  "44th day of the Omer"
                ]
              }
            application/xml:
              gregorian:
                year: "2011" 
                month: "6" 
                day: "2"
              hebrew:
                year="5771" 
                month="Iyyar" 
                day="29" 
                str="כ״ט בְּאִיָיר תשע״א" 
definitions:
  Date:
    type: object
    properties: 
      gy:
        type: integer
        description: Gregorian year
      gm:
        type: integer
        description: Gregorian month
      gd:
        type: integer
        description: Gregorian day of the month
      hy:
        type: integer
        description: Hebrew year
      hm:
        type: string
        description: Hebrew month
      hd:
        type: integer
        description: Hebrew day of the month
      hebrew:
        type: string
        description: Long date in Hebrew
      events:
        type: array
        description: List of events for that date
        items: 
          type: string
          description: Event title

It would be usefull to have some boolean like isShabbos=true so that sites that if a client of this API wants to be inaccessible on Shabbos, this would be convenient