swagger.yaml

swagger: "2.0"
info:
  description: "An API used to generate tables in a variety of formats (html, xlsx, csv) from a json source. Also capable of parsing an html table and producing json."
  version: "1.0.0"
  title: "Table Renderer API"
  license:
    name: "Open Government Licence v3.0"
    url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
schemes:
- "http"
paths:
  /render/{render_type}:
    post:
      summary: "Generate a table from json input"
      description: "Create an html, csv or xlsx representation of the given table for display or download"
      consumes:
        - "application/json"
      produces:
        - "text/html"
        - "text/csv"
        - "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
      parameters:
        - name: render_type
          type: string
          enum: [html, csv, xlsx]
          required: true
          description: "The type of output required"
          in: path
        - name: table_definition
          schema:
            $ref: '#/definitions/RenderRequest'
          required: true
          description: "The definition of the table to be generated"
          in: body
      responses:
        '200':
          description: "An appropriate representation of the table is returned in the body"
        '400':
          description: "Invalid request body"
        '404':
          description: "Unknown render type"
        '500':
          $ref: '#/responses/InternalError'
  /parse/html:
    post:
      summary: "Parse an html table and generate a json definition"
      description: "A request to convert an html table (plus supporting data) into the correct RenderRequest format"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: parse_request
          schema:
            $ref: '#/definitions/ParseRequest'
          required: true
          description: "Object containing the html of the table to be parsed, plus supporting information"
          in: body
      responses:
        '200':
          description: "A json representation of the table is returned in the body"
          schema:
            $ref: '#/definitions/ParseResponse'
        '400':
          description: "Invalid request body"
        '500':
          $ref: '#/responses/InternalError'
responses:
  InternalError:
    description: "Failed to process the request due to an internal error"
definitions:
  RenderRequest:
    description: "A definition of a table that should be rendered"
    type: object
    required: ["filename"]
    allOf:
    - $ref: '#/definitions/TableMetaData'
    - type: object
      properties:
        row_formats:
          type: array
          description: "A list of format definitions for rows of the table"
          items:
            $ref: '#/definitions/RowFormat'
        column_formats:
          type: array
          description: "A list of format definitions for columns of the table"
          items:
            $ref: '#/definitions/ColumnFormat'
        cell_formats:
          type: array
          description: "A list of format definitions for individual cells in the table"
          items:
            $ref: '#/definitions/CellFormat'
        data:
          type: array
          description: |
            The content of the cells in the table (a two-dimensional array of strings).
            Should contain values for each possible cell in the table,
            even if that cell will be hidden because another cell has a colspan or rowspan that covers it.
          items:
            type: array
            items:
              type: string
  RowFormat:
    description: |
      A specification that a given row should be formatted in a particular way - as a header, or with vertical alignment
    type: object
    properties:
      row:
        type: integer
        description: "The index of the row this format applies to. Zero indexed."
      heading:
        type: boolean
        description: 'Whether this row should be formatted as a heading'
      height:
        type: string
        description: "The desired height of this row, as a valid css width property. E.g. '5em'"
      vertical_align:
        type: string
        description: |
          The vertical alignment of the row.
          For html output this will be rendered as the name of a css class
          that is assumed to be defined in the containing page.
        enum: [Top, Middle, Bottom]
  ColumnFormat:
    description: |
      A specification that a given column should be formatted in a particular way - as a header, or with a specific width
    type: object
    properties:
      col:
        type: integer
        description: "The index of the column this format applies to. Zero indexed."
      heading:
        type: boolean
        description: 'Whether this column should be formatted as a heading'
      width:
        type: string
        description: "The desired width of this column, as a valid css width property. E.g. '5em'"
      align:
        type: string
        description: |
          The alignment of the column.
          For html output this will be rendered as the name of a css class
          that is assumed to be defined in the containing page.
        enum: [Left, Center, Right, Justify]
  CellFormat:
    description: |
      A specification that a given cell should be formatted in a particular way
       - with alignment or spanning multiple columns/rows
    type: object
    properties:
      row:
        type: integer
        description: "The row index of the cell this format applies to. Zero indexed."
      col:
        type: integer
        description: "The column index of the cell this format applies to. Zero indexed."
      align:
        type: string
        description: |
          The alignment of the column.
          For html output this will be rendered as the name of a css class
          that is assumed to be defined in the containing page.
        enum: [Left, Center, Right, Justify]
      vertical_align:
        type: string
        description: |
          The vertical alignment of the cell.
          For html output this will be rendered as the name of a css class
          that is assumed to be defined in the containing page.
        enum: [Top, Middle, Bottom]
  ParseRequest:
    description: "A model for the response body when retrieving a filter output"
    type: object
    required: ["filename", "table_html"]
    allOf:
    - $ref: '#/definitions/TableMetaData'
    - type: object
      properties:
        table_html:
          type: string
          description: "An html snippet containing the <table>...</table> that should be parsed"
        ignore_first_row:
          type: boolean
          description: |
            If true, the first row in the source table is ignored. Can be useful with some js spreadsheet components
            that insert row and column headers.
        ignore_first_column:
          type: boolean
          description: |
            If true, the first cell of each row in the source table is ignored. Can be useful with some js spreadsheet
            components that insert row and column headers.
        header_rows:
          type: integer
          description: |
            The number of rows that should be rendered as headings, after ignoring the first row (if applicable).
        header_cols:
          type: integer
          description: |
            The number of column that should be rendered as headings, after ignoring the first row (if applicable).
        cell_size_units:
          type: string
          description: |
            The desired unit for cell widths/heights. Pixel widths will be converted to this unit, provided the
            required information is provided - see current_table_width and single_em_height. The default is 'auto',
            in which case no table cell widths/heights will be specified.
          enum: ["%", "em", "auto"]
        current_table_width:
          type: integer
          description: |
            The width of the table, used to convert pixel widths to %.
        current_table_height:
          type: integer
          description: |
            The height of the table, used to convert pixel heights to %.
        single_em_height:
          type: number
          description: |
            Used to convert height/width from pixels to em. The height of the following:
            <div style="display: none; font-size: 1em; margin: 0; padding:0; height: auto; line-height: 1; border:0;">m</div>.
        column_width_to_ignore:
          type: string
          description: |
            If the source html applies a default column width that shouldn't be included in the output, specify it here.
            e.g. '50px'
        alignment_classes:
          description: |
            The names of classes that should be interpreted as defining alignment of cells. The presence of these classes
            on table cells will be used to determine the align & vertical_align properties of row/column/cell formats.
          $ref: '#/definitions/AlignmentClasses'
  AlignmentClasses:
    description: "defines the css classes that should be interpreted as defining the alignment of cells in a table"
    type: object
    properties:
      top:
        type: string
        description: "The css class indicating vertical alignment at the top"
      middle:
        type: string
        description: "The css class indicating vertical alignment in the middle"
      bottom:
        type: string
        description: "The css class indicating vertical alignment at the bottom"
      left:
        type: string
        description: "The css class indicating alignment on the left"
      center:
        type: string
        description: "The css class indicating alignment in the centre"
      right:
        type: string
        description: "The css class indicating alignment on the right"
  TableMetaData:
    description: "Properties that are present in both the RenderRequest and ParseRequest"
    type: object
    required: ["filename"]
    properties:
      filename:
        type: string
        description: "A unique id for the table"
      title:
        type: string
        description: "The main title of the table"
      subtitle:
        type: string
        description: "An additional title or short description of the table"
      source:
        type: string
        description: "Where the data in the table came from"
      units:
        type: string
        description: "Name/decription of the units used in the table, if appropriate"
      keep_headers_together:
        type: boolean
        description: "If true, the html output includes a css class designed to prevent content of heading cells being wrapped over 2 lines. Deliberate line breaks will be honoured."
      footnotes:
        type: array
        description: |
          Notes associated with (and potentially referenced from) the table.
          The order of footnotes is important, e.g. [1] will be converted into a link to the first footnote.
        items:
          type: string
  ParseResponse:
    description: "The response to a parse requests - contains an html representation of the table, and the json that defines it"
    type: object
    properties:
      render_json:
        $ref: '#/definitions/RenderRequest'
      preview_html:
        type: string
        description: "The html of the table as it would be generated from json"