gistfile1.txt

swagger: "2.0"
info:
  title: ycmd
  description: |-
    ycmd is a code-completion & code-comprehension server

    ## General Notes

    - All strings going into and out of the server are UTF-8 encoded.
    - All line and column numbers are 1-based, not 0-based. They are also byte
      offsets, not Unicode codepoint offsets.
    - All file paths are full, absolute paths.
    - All requests to the server must include an HMAC in the x-ycm-hmac HTTP
      header. The HMAC is computed from the shared secret passed to the server
      on startup and the request/response body. The digest algorithm is SHA-256.
      The server will also include the HMAC in its responses; you must verify it
      before using the response. See example_client.py to see how it's done.

    ## Command line options

    ## HMAC

  version: 0.0.1
definitions:
  LineNumber:
    type: integer
    description: 1-based line number
  ColumnNumber:
    type: integer
    description: 1-based column byte offset within the line 
  FilePath:
    type: string
    description: |-
      Absolute path to the file in the filesystem. If the file does 
      not yet exist (for example, a new file), then the value may be the empty 
      string.
  FileData:
    type: object
    description: |-
      Contents and details of a dirty buffer.
    required:
      - filetypes
      - contents
    properties:
      filetypes: 
        type: array
        items:
          type: string
      contents:
        type: string
        description: The entire contents of the buffer encoded as UTF-8
  FileDataMap:
    type: object
    description: |-
      An object mapping whose keys are the absolute paths to the 
      files and whose values are data relating to dirty buffers.
    additionalProperties:
      $ref: "#/definitions/FileData"

  # Due to the way the API combines keys at the top level, we are not able to 
  # compose this item per-request. So this definition is actually not used, but
  # is kept here as a source of copypasta.
  RequestData:
    type: object
    description: |-
      Basic details of a request, such as the current location of the cursor
      and the contents of dirty buffers.
    required:
      - line_num
      - column_num
      - filepath
    properties:
      line_num:
        $ref: "#/definitions/LineNumber"
      column_num:
        $ref: "#/definitions/ColumnNumber"
      filepath:
        $ref: "#/definitions/FilePath"
      file_data:
        $ref: "#/definitions/FileDataMap"

  Exception:
    type: object
    description: JSON-encoded representation of a Python Exception object.
    # We don't document the contents of this object, as it is defined in the
    # Python documentation.
    additionalProperties: true

  ExceptionResponse:
    type: object
    description: |-
      The server raised an exception processing the request. This response is 
      often returned when the server is unable to perform the requested action,
      not due to a bug or other error, but because it is not possible to do so.
      For example, it is common for an exception response to be returned when
      requesting "GoToDefinition" on an identifier for which the semantic,
      engine is unable to find such a definition.
    properties:
      exception:
        $ref: "#/definitions/Exception"
      message:
        type: string
        description: |-
          The exception message. Typically a single line and suitable for
          display to a user.
      traceback:
        type: string
        description: |-
          A detailed report of the ycmd call stack at the point the exception
          was thrown. It is typically not required to display this to a user,
          as ycmd will print all exceptions to its log file (standard error).

  Location:
    type: object
    description: A location within a source buffer
    properties:
      line_num:
        $ref: "#/definitions/LineNumber"
      column_num:
        $ref: "#/definitions/ColumnNumber"
      filepath:
        $ref: "#/definitions/FilePath"

  Range:
    type: object
    description: A contiguous range of bytes in a source buffer
    properties:
      start:
        type: object
        properties:
          $ref: "#/definitions/Location/properties"
        description: The start of the range
      end:
        type: object
        properties:
          $ref: "#/definitions/Location/properties"
        description: The end of the range

  DiagnosticData:
    type: object
    required:
      - ranges
      - location
      - location_extent
      - text
      - kind
    properties:
      ranges:
        type: array
        description: |-
          List of ranges to which this diagnostic applies.
          TODO: What?
        items:
          $ref: "#/definitions/Range"
      location:
        type: object
        properties:
          $ref: "#/definitions/Location/properties"
        description: |-
          The source location where the diagnostic applies. This is typically
          (but not always) the start of `location_extent`.
      location_extent:
        type: object
        properties:
          $ref: "#/definitions/Range/properties"
        description: |-
          The source range to which the diagnostic applies. This differs from 
          the `location` in that it refers to the whole range. Typically this is
          used to underline, or otherwise render as "error" the source code
          which caused the diagnostic.
      text:
        type: string
        description: The diagnostic text (e.g. error message)
      kind:
        type: string
        # TODO: is this the real set of values?
        enum:
          - WARNING
          - ERROR
        description: |-
          The type of diagnostic being reported. Typically semantic engines will
          differentiate between warnings and fatal errors.
      fixit_avvailable:
        type: boolean
        description: |-
          If set to true, indicates that a quick fix action (FixIt) is
          available for this diagnostic. Typically this is used to indicate to
          the user that the `FixIt` subcommand is available.
  DiagnosticResponse:
    type: array
    items: 
      $ref: "#/definitions/DiagnosticData"
    
paths:
  /event_notification:
    get:
      summary: Notify the server of various client events
      description: |-
        The server needs to react to a number of client events in order to 
        provide things like diagnotics and to handler downstream server states 
        etc. The client must inform the server of the following events, 
        populating the event name in the `event_name` property:
          - `FileReadyToParse`
            Call when a new buffer is opened or after the user has 
            stopped typing for some time, or at any other time when the client
            believes that it is worthwhile reparsing the current file and 
            updating semantic engines' ASTs and reporting things like updated
            diagnostics.
          - `BufferUnload`
            Call when the user closes a buffer that was previously known to be
            open. *Note*: the `unloaded_buffer` property is required.
          - `BufferVisit`
            Call when the user focusses on a buffer that is already known.
            *Note*: The `ultisnips_snippets` property is optional when firing
            calling this event. TODO: Otherwise it is ignored.
          - `InsertLeave`
            For modal editors, call when exiting insert mode.
            TODO: When should this *really* be called? This is sounding very 
            Vim-specific. I wonder what the other editor plugins do.
          - `CurrentIdentifierFinished`
            Call when the user finishes typic what appear to the client to be
            an identifier.
            TODO: How should the client know when this has happened?
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The notification data. The line and column are typically not used,
            but the `filepath` and file data properties are used to perform
            semantic analysis (e.g. in the `FileReadyToParse` handler)
          required: true
          schema:
            type: object
            required:
              - line_num
              - column_num
              - filepath
              - event_name
            properties:
              line_num:
                $ref: "#/definitions/LineNumber"
              column_num:
                $ref: "#/definitions/ColumnNumber"
              filepath:
                $ref: "#/definitions/FilePath"
              file_data:
                $ref: "#/definitions/FileDataMap"
              event_name:
                type: string
                enum: 
                  - FileReadyToParse
                  - BufferUnload
                  - BufferVisit
                  - InsertLeave
                  - CurrentIdentifierFinished
                description: The event that occurred.
              unloaded_buffer:
                type: string
                description: |-
                  *Required when `event_name` is BufferUnload*
                  The absolute path of the buffer which was unloaded.
              ultisnips_snippets:
                type: object
                description: |-
                  *Optional when `event_name` is BufferVisit*
                  Supplies the ultisips snippets known for the current
                  filetypes. Can be used to supply any other type of additional
                  completion suggestions generated by the client.
                required:
                  - trigger
                  - description
                properties:
                  trigger:
                    type: string
                    description: |-
                      The text to insert in order to trigger the snippet. When
                      supplying non-ultisnips suggestions, this is the text
                      to be inserted.
                  description:
                    type: string
                    description: |-
                      Additional text to display in the completion menu, such
                      as a summary of the snippet to be inserted.
      responses:
        200: 
          description: Optional set of diagnostics for the current buffer
          schema:
            $ref: "#/definitions/DiagnosticResponse"
        500:
          description: An error occurred
          schema:
            $ref: "#/definitions/ExceptionResponse"
externalDocs: 
  description: ycmd GitHub page
  url: https://github.com/Valloric/ycmd