openapi.yml

# Copyright (C) 2017-2018 ycmd contributors.
#
# This file is part of ycmd.
#
# ycmd is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# ycmd is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with ycmd.  If not, see <http://www.gnu.org/licenses/>.
swagger: "2.0"
info:
  title: ycmd
  description: |-
    ycmd is a code-completion & code-comprehension server.

    ycmd presents a JSON/REST interface to clients over HTTP, validated by HMAC.
    An instance of ycmd is started for each client application.

    ## General Notes

    The REST interface typically uses HTTP POST requests and expects the payload
    data to be a valid JSON document. The following general principles are
    applied:

    - All strings going into and out of the server are UTF-8 encoded.
    - All lines end with `\n`.
    - 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. If a file has not been written
      to disk yet, supply a temporary path.
    - All requests to the server must include an HMAC in the x-ycm-hmac HTTP
      header.
    - All responses from the server must be validated using the x-ycm-hmac
      header.

    ## The example client

    ycmd contains a simple example client in the `example` directory of the
    source tree. It is written in pure Python with only minimal dependencies.
    It contains trivial implementations of most endpoints and serves to
    supplement this API documentation.

    Consult `example/README.md` for instructions on getting it running.

    ## Starting the server

    The ycmd server is typically started by a client in order to provide
    services to it. Briefly, starting the server requires supplying some
    configuration and initializing some security features (HMAC).

    The server should be started with a supported version of Python.

    The full list of command line options can be obtained by passing `--help`
    to ycmd (e.g. `python -m ycmd --help`). However, the following
    options warrant further discussion:

    ### `--options_file`

    This mandatory option supplies the name of a file containing user options
    data. This option (and thus the file) are mandatory, as they are required
    to set the shared HMAC secret.

    Once the server has read the options, the server deletes the options file.
    Therefore, the client should typically create a secure temporary file (e.g.
    `mkstemp`) which contains the options to be used.

    The default options and their values are found in `default_settings.json`
    within the ycmd codebase.

    The file contains a JSON-formatted object, where the keys are the names of
    options (with any `ycm_` prefix removed) and the values are the option
    values.

    The canonical list of supported user options can be found in
    YouCompleteMe's `README.md`. The option values should have the `ycm_`
    prefix removed.

    The following additional options are required to be set by the client
    application and should *not* be visible to the user:

      - `hmac_secret`: The shared secret for HMAC authentication. This should be
        16 bytes of random data with as much entropy as possible, encoded as a
        base-64 UTF-8 string. Code for generating this in Python can be found
        in the ycmd example client.

    ## HMAC

    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 the example client to see how it's done.

    ## Filetypes

    ycmd uses `filetypes` to identify the "language" of a given buffer. These
    filetype values are strictly the values understood by Vim. Please see the
    YCM README.md for the list of filetypes recognized by ycmd for semantic
    completion.

  version: 0.3.0

externalDocs:
  description: ycmd GitHub page
  url: https://github.com/Valloric/ycmd

definitions:
  YesNo:
    type: boolean
    description: "Result of the query: `true` if yes, `false` otherwise."
  AlwaysYes:
    type: boolean
    description: "`true` is always returned, unless there is an error."
  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 should be an
      arbitrary unique string.
  CompleterTarget:
    type: string
    description: |-
      The completer implementation for which the command is intended. Typically,
      this is set to `filetype_default`, but may also take any of the following
      values:
        - `filetype_default`
          Use the semantic completer associated with the filetype of the current
          buffer. This is the default when a target is not supplied.
        - `identifier`
          Use the identifier completer.
        - Any filetype
          Use the completer associated with the supplied filetype.
  WorkingDirectory:
    type: string
    description: |-
      Absolute path to the filesystem working directory of the client. This is
      used by completer engines to determine things like the project root
      for the file being modified, amongst other things.
  ExtraConfData:
    type: object
    description: |-
      A dictionary passed to the `Settings( **kwargs )` function of the
      `.ycm_extra_conf.py` file under the `client_data` key of `kwargs`. This
      optional field should be used to give users a way to customize the
      `.ycm_extra_conf.py` file with their own set of options.
  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 unsaved buffers.

      An unsaved buffer is any file that is opened in the editor and has been
      changed without saving the contents to disk.

      The file referred to in the request `filepath` entry must _always_ be
      included. For most requests this is the user's current buffer, but may
      be any buffer (e.g. in the case of closing a buffer which is not current).

      When a file is closed in the editor, a `BufferUnload` event should be sent
      and the file should not be included in further `FileDataMap` entries
      until (or unless) it is opened and changed again.

    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 must be copy-pasted for
  # some requests.
  SimpleRequest:
    type: object
    required:
      - line_num
      - column_num
      - filepath
      - file_data
    properties:
      line_num:
        $ref: "#/definitions/LineNumber"
      column_num:
        $ref: "#/definitions/ColumnNumber"
      filepath:
        $ref: "#/definitions/FilePath"
      file_data:
        $ref: "#/definitions/FileDataMap"
      completer_target:
        $ref: "#/definitions/CompleterTarget"
      working_dir:
        $ref: "#/definitions/WorkingDirectory"
      extra_conf_data:
        $ref: "#/definitions/ExtraConfData"

  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 contiguous range of bytes in a source buffer starting at `start` and
      finishing at `end`. The range is (effectively) exclusive. That is if start
      points to (10,1) and end points to (10,3), then the length of the range
      is 2 characters.
    required:
      - line_num
      - column_num
      - filepath
    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.
    required:
      - start
      - end
    properties:
      start:
        $ref: "#/definitions/Location"
      end:
        $ref: "#/definitions/Location"

  DiagnosticData:
    type: object
    description: |-
      - `location`
        The source location where the diagnostic applies. This is typically
        (but not always) the start of `location_extent`.
      - `location_extent`
        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.
    required:
      - ranges
      - location
      - location_extent
      - text
      - kind
    properties:
      ranges:
        type: array
        description: |-
          List of ranges to which this diagnostic applies. These ranges
          typically identify the source locations which should be
          "highlighted" as incorrect.
        items:
          $ref: "#/definitions/Range"
      location:
        $ref: "#/definitions/Location"
      location_extent:
        $ref: "#/definitions/Range"
      text:
        type: string
        description: The diagnostic text (e.g. error message)
      kind:
        type: string
        enum:
          - WARNING
          - ERROR
          - INFORMATION
          - HINT
        description: |-
          The type of diagnostic being reported. Typically semantic engines will
          differentiate between warnings and fatal errors. Informational and
          hint messages should be treated as warnings where the client does not
          differentiate.
      fixit_available:
        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"

  FixIt:
    type: object
    required:
      - location
      - chunks
    properties:
      text:
        type: string
        description: |-
          The diagnostic text or a description of the modification to be made.
          This is the text displayed to the user when selecting from multiple
          available FixIts.
      location:
        $ref: "#/definitions/Location"
      chunks:
        type: array
        description: |-
          A list of ranges and replacements which must be applied to source
          files. *NOTE*: The source ranges may span arbitrary files and the
          sequence of `chunks` is not defined.
        items:
          type: object
          required:
            - replacement_text
            - range
          properties:
            replacement_text:
              type: string
              description: |-
                The text with which to replace the range identified by `range`.
            range:
              $ref: "#/definitions/Range"

  Candidate:
    type: object
    properties:
      insertion_text:
        type: string
        description: |-
          The word to insert when selecting the completion.

          Equivalent of the Vim `complete-items` entry: `word`.
      menu_text:
        type: string
        description: |-
          The word to display as the suggestion to the user. If not
          supplied, `insertion_text` is displayed to the user.

          Equivalent of the Vim `complete-items` entry: `abbr`.
      extra_menu_info:
        type: string
        description: |-
          Additional information to display about the suggestion within
          the completion menu (or equivalent). Typically this is the
          signature/declaration of the item being suggested, or some
          additional free-text qualifiers (such as `[File]` etc.). These
          are a single line and typically short. For more detailed
          information, such as usage and docs, see `detailed_info`.

          Equivalent of the Vim `complete-items` entry: `menu`.
      detailed_info:
        type: string
        description: |-
          Additional information, such as the full signature and method
          documentation, suitable for display in a preview window or
          tooltip.

          Equivalent of the Vim `complete-items` entry: `info`.
      kind:
        type: string
        description: |-
          An indicator of the type of suggestion. Only the first character
          of `kind` should be displayed.

          Equivalent of the Vim `complete-items` entry: `kind`.
      extra_data:
        type: object
        description: |-
          Completer-specific additional information.
        properties:
          doc_string:
            type: string
            description: |-
              Additional documentation/information to be displayed
              alongside (after) information in `detailed_info`.

  CompletionResponse:
    type: object
    required:
      - completions
      - completion_start_column
    properties:
      completions:
        type: array
        description: List of completion suggestions.
        items:
          $ref: "#/definitions/Candidate"
      completion_start_column:
        type: integer
        description: |-
          1-based byte index of the column from which the completion should be
          applied. This is the column in which the words suggested in
          `completions` should be placed.
      errors:
        type: array
        description: Any errors reported by the semantic completion engine.
        items:
          $ref: "#/definitions/ExceptionResponse"

  ItemData:
    type: object
    required:
      - key
      - value
    properties:
      key:
        type: string
      value:
        type: string

  ServerData:
    type: object
    required:
      - name
      - is_running
      - executable
      - address
      - port
      - pid
      - logfiles
      - extras
    properties:
      name:
        type: string
        description: The server name.
      is_running:
        type: boolean
        description: |-
          `true` if the server is running, `false` otherwise.
      executable:
        type: string
        description: The executable path used to start the server.
      address:
        type: string
        description: |-
          The address on which the server is listening. `null` if not
          applicable.
      port:
        type: integer
        description: |-
          The port on which the server is listening. `null` if not applicable.
      pid:
        type: integer
        description: |-
          The process identifier of the server. `null` if the server is not
          running.
      logfiles:
        type: array
        description: A list of logging files used by the server.
        items:
          type: string
          description: A logging file path.
      extras:
        type: array
        items:
          $ref: "#/definitions/ItemData"

  DebugInfoResponse:
    type: object
    required:
      - name
      - servers
      - items
    properties:
      name:
        type: string
        description: The completer name.
      servers:
        type: array
        description: A list of servers used by the completer.
        items:
          $ref: "#/definitions/ServerData"
      items:
        type: array
        description: Additional debugging information.
        items:
          $ref: "#/definitions/ItemData"

  MessagePollResponse:
    type: boolean
    description: |-
      When `true` is returned, the request timed out (meaning no
      messages were returned in the poll period). Clients should
      send another `receive_messages` request immediately.

      When `false` is returned, the server determined that message
      polling should abort for the current file type context. Clients
      should not re-send this request until the filetype being edited
      changes or the server is restarted.

  MessageList:
    type: array
    description: |-
      A list of messages in the sequence they should be handled.

      The type of message in each item is determined by the property name:

      - An object with a property `message` is a *simple display message* where
        the property value is the message.
      - An object with a property `diagnostics` contains diagnotics for a
        project file. The value of the property is described below.
    items:
      $ref: '#/definitions/Message'

  Message:
    type: object
    description:
      An object containing a single asynchronous message.

      It is either a `SimpleDisplayMessage` or a `DiagnosticsMessage`
    properties:
      message:
        $ref: '#/definitions/SimpleDisplayMessage'
        description: If present, this object is a `SimpleDisplayMessage`
      diagnostics:
        $ref: '#/definitions/DiagnosticsMessage'
        description: If present, this object is a `DiagnosticsMessage`

  SimpleDisplayMessage:
    type: string
    description: |-
      A message for display to the user. Note: the message should be displayed
      discreetly (such as in a status bar) and should not block the user or
      interrupt them.

  DiagnosticsMessage:
    type: object
    description: |-
      Diagnostics for a particular file. Note: diagnostics may be supplied for
      any arbitrary file. The client is responsible for displaying the
      diagnostics in an appropriate manner. The server supplies an empty set of
      diagnostics to clear the diagnostics for a particular file.
    required:
      - filepath
      - diagnostics
    properties:
      filpath:
        $ref: '#/definitions/FilePath'
      diagnotics:
        type: array
        items:
          $ref: "#/definitions/DiagnosticData"

paths:
  /event_notification:
    post:
      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 diagnostics and to handle 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. Closing buffers is important to limit resource usage.
          - `BufferVisit` (optional)
            Call when the user focusses on a buffer that is already known.
            *Note*: The `ultisnips_snippets` property is optional when firing
            calling this event. Otherwise it is ignored.
          - `InsertLeave` (optional)
            For modal editors, call when exiting insert mode. It is equivalent
            to `CurrentIdentifierFinished`.
          - `CurrentIdentifierFinished` (optional)
            Call when the user finishes typing what appears to the client to be
            an identifier.
      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
              - file_data
              - event_name
            properties:
              line_num:
                $ref: "#/definitions/LineNumber"
              column_num:
                $ref: "#/definitions/ColumnNumber"
              filepath:
                $ref: "#/definitions/FilePath"
              file_data:
                $ref: "#/definitions/FileDataMap"
              completer_target:
                $ref: "#/definitions/CompleterTarget"
              working_dir:
                $ref: "#/definitions/WorkingDirectory"
              extra_conf_data:
                $ref: "#/definitions/ExtraConfData"
              event_name:
                type: string
                enum:
                  - FileReadyToParse
                  - BufferUnload
                  - BufferVisit
                  - InsertLeave
                  - CurrentIdentifierFinished
                description: The event that occurred.
              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.
            example:
              line_num: 10
              column_num: 20
              filepath: "/home/test/dev/test.js"
              file_data:
                "/home/test/dev/test.cc":
                  filetypes: [ 'cpp' ]
                  contents: "<file contents>"
              event_name: "FileReadyToParse"
      responses:
        200:
          description: Optional set of diagnostics for the current buffer.
          schema:
            $ref: "#/definitions/DiagnosticResponse"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /run_completer_command:
    post:
      summary: Run a semantic completer subcommand.
      description: |-
        Semantic completers offer additional engine-specific commands, known
        as completer subcommands. This endpoint requests a specific command to
        be executed. Typically the "default" semantic completer for the current
        filetype is used, but it is possible to force the use of a particular
        completer, using the `completer_target` property.

        The command to execute is passed as a list of arguments, the first of
        which is the command name followed by any command- and
        completer-specific additional arguments. This "command line" is passed
        in the `command_arguments` property.

        The list of available subcommands for a particular semantic completer
        can be queried using the `/defined_subcommands` endpoint.

        Subcommands may return one of a number of actions, depending on the
        type of command. The following types of response are returned:

        - A *simple display message* response. This is identified where the
          type of the response is scalar (i.e. boolean, number, string) or the
          type of the response is an object with a `message` property. These
          messages are typically only a single line and can be displayed in
          a message-box or similarly echoed in a status bar or equivalent.
        - A *FixIt* response. This is identified where the type of the response
          is an object with a property named `fixits`.
        - A *detailed information* response. This is identified where the type
          of the response is an object with a `detailed_info` property. These
          messages are typically multiple lines (such as the documentation and
          signature for a method) and are best displayed in a panel or preview
          area (or equivalent).
        - A *GoTo* response. This is identified where the response type cannot
          be determined by any of the above methods. A GoTo response may contain
          either a single location (e.g. for `GoToDeclaration`), or a list of
          possible locations for the user to chose from (such as in a
          `GoToReferences` subcommand).
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            type: object
            required:
              - line_num
              - column_num
              - filepath
              - file_data
              - command_arguments
              - options
            properties:
              line_num:
                $ref: "#/definitions/LineNumber"
              column_num:
                $ref: "#/definitions/ColumnNumber"
              filepath:
                $ref: "#/definitions/FilePath"
              file_data:
                $ref: "#/definitions/FileDataMap"
              completer_target:
                $ref: "#/definitions/CompleterTarget"
              working_dir:
                $ref: "#/definitions/WorkingDirectory"
              extra_conf_data:
                $ref: "#/definitions/ExtraConfData"
              command_arguments:
                type: array
                description: |-
                  The command line to execute as a list of arguments. The first
                  such argument is the subcommand to execute (for example:
                  `GoTo`).
                items:
                  type: string
              range:
                description: |-
                  The range to which the command is applied (only used by the
                  *Format* command).
                $ref: "#/definitions/Range"
              options:
                type: object
                description: |-
                  A set of editor-related options for the current buffer (only
                  used by the *Format* command).
                required:
                  - tab_size
                  - insert_spaces
                properties:
                  tab_size:
                    description: The size of a tabulation in spaces.
                    type: integer
                  insert_spaces:
                    description: Use spaces to represent tabulations.
                    type: boolean
            example:
              line_num: 10
              column_num: 20
              filepath: "/home/test/dev/test.js"
              file_data:
                "/home/test/dev/test.js":
                  filetypes: [ 'javascript' ]
                  contents: "<file contents>"
              completer_target: "filetype_default"
              command_arguments: [ 'RefactorRename', 'Testing' ]
              options:
                tab_size: 4
                insert_spaces: true
      responses:
        200:
          description: |-
            Optional action or display text in response to the request.

            *NOTE*: If the type of the response is not an object or list,
                    then the response is a *simple display message*.

            *NOTE*: If the type of the response is a list, then the response is
                    a GoTo list (e.g. quick-fix list or equivalent) and the
                    items in the list are of type `GoToLocations`
                    (see definitions).
          schema:
            type: object
            properties:
              fixits:
                type: array
                description: |-
                  If present, this is a *FixIt* or *Refactor* response and the
                  value of this property is a list of potential changes to
                  buffers to apply the quick fix or refactoring operation.

                  An empty `fixits` list means that no FixIt or refactoring
                  was available. If multiple entries are supplied, the user is
                  prompted to select which one to apply.
                items:
                  $ref: "#/definitions/FixIt"
                maxItems: 1
                minItems: 0
              message:
                type: string
                description: |-
                  If present, this is a *simple display message* and the value
                  of this property is the message to display.
              detailed_info:
                type: string
                description: |-
                  If present, this is a *detailed information* response and
                  the value of this property is the multi-line information
                  to display as unformatted plain text.
              filepath:
                type: string
                description: |-
                  If present, this is a single *GoTo response* and this value
                  contains the absolute path of the buffer containing the
                  target location (identified in `line_num` and `column_num`).
              line_num:
                $ref: "#/definitions/LineNumber"
              column_num:
                $ref: "#/definitions/ColumnNumber"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /completions:
    post:
      summary: Get completion suggestions for the current file context.
      description: |-
        Returns the autocompletion suggestions for the current cursor
        position. Typically, the server determines whether or not to use
        semantic completion or general (i.e. identifier-based) completion
        based on the language (filetype) and the context. Clients can force
        the use of semantic completion by setting the `force_semantic`
        property to `true`.

        Note that if `force_semantic` is not set to `true` and the completion
        engine returns an error, the server still tries to fall back to
        general completion, so this endpoint will typically always return
        successfully. Any semantic completer error raised is included in the
        response to be dealt with by the client.

        When `force_semantic` is `true`, any error returned by the semantic
        engine is returned via a 500 response.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: The list of completion suggestions.
          schema:
            $ref: "#/definitions/CompletionResponse"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /filter_and_sort_candidates:
    post:
      summary: Filter and sort a set of candidates using ycmd's fuzzy matching.
      description: |-
        For filetypes not natively supported by ycmd, clients can often
        determine a set of suitable candidate completion suggestions by other
        means. In Vim this is typically from the `omnifunc` and other clients
        will have equivalents.

        This endpoint allows clients to use ycmd's powerful filtering and
        ranking capabilities (including longest-common-subsequence and
        word-boundary-character ranking) on arbitrary sets of identifiers.

        *NOTE:* This API is primarily intended for use when subclassing the
                `Completer` class outside of ycmd which is a very niche case,
                specific to the `OmniCompleter` in the Vim client. It is not
                expected that this API be used elsewhere.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          required: true
          description: |-
            The set of candidates to sort of the query parameters.

            *NOTE:* This `request_data` object is different from most other
                    ycmd requests as it does not contain buffer data or
                    cursor locations.
          schema:
            type: object
            properties:
              candidates:
                type: array
                description: The candidates to filter and sort
                items:
                  $ref: "#/definitions/Candidate"
              sort_property:
                type: string
                enum:
                  - word
                  - insertion_text
                description: |-
                  Typically set to `insertion_text`, but can be set to `word` when
                  the candidates are in the form of a simple list of words. In
                  the latter case, `candidates` must be a list of strings.
              query:
                type: string
                description: |-
                  The text the user has typed so far for the current identifier.
                  This is to filter against the suggestions in `candidates`.
      responses:
        200:
          description: The filtered list of candidated
          schema:
            type: array
            items:
              $ref: "#/definitions/Candidate"
        500:
          description: An error occurred
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /healthy:
    get:
      summary: Check if the server is healthy.
      description: |-
        Return `true` if the server is healthy, `false` otherwise. The client
        should use this endpoint to keep the server alive.
      # We don't document the subserver query parameter as it is only for
      # testing.
      produces:
        - application/json
      responses:
        200:
          description: Server is healthy.
          schema:
            $ref: "#/definitions/AlwaysYes"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/ExceptionResponse"

  # We don't document the /ready handler as it is only for testing.

  /semantic_completer_available:
    post:
      summary: Determine if semantic completion is available for current buffer.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: Whether or not semantic completion is available.
          schema:
            $ref: "#/definitions/YesNo"
        500:
          description: An error occurred
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /defined_subcommands:
    post:
      summary: Get the list of subcommands which are available for a completer.
      description: |-
        Returns the list of completer subcommands for a given completer.

        See also: `/run_completer_command`
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: The list of available subcommands.
          schema:
            type: array
            items:
              type: string
        500:
          description: An error occurred
          schema:
            $ref: "#/definitions/ExceptionResponse"


  /detailed_diagnostic:
    post:
      summary: Get additional information about diagnostic under cursor.
      description: |-
        Where available returns addition information about the diagnostic, such
        as the full text of the compile error, suggestions, etc.

        Typically, details are returned for the diagnostic nearest to the
        current cursor position.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: The detailed diagnostic
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
        500:
          description: An error occurred, or no diagnostic was available
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /load_extra_conf_file:
    post:
      summary: Forcefully load the config for the current buffer.
      description: |-
        By default, ycmd will not load `.ycm_extra_conf.py` files for security
        reasons and instead raises an exception the first time it requires
        loading.

        In the case that exception is raised, the client should call this
        API endpoint after confirming with the user that it is safe to load
        the reported `.ycm_extra_conf.py` file.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: Configuration file loaded.
          schema:
            $ref: "#/definitions/AlwaysYes"
        500:
          description: An error occurred loading the configuration file.
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /ignore_extra_conf_file:
    post:
      summary: Forcefully ignore the config for the current buffer.
      description: |-
        As opposed to `/load_extra_conf_file`, this API endpoint must be called
        when the user declines to load the associated `.ycm_extra_conf.py` file.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: Configuration file ignored.
          schema:
            $ref: "#/definitions/AlwaysYes"
        500:
          description: An error occurred ignoring the configuration file.
          schema:
            $ref: "#/definitions/ExceptionResponse"

  /debug_info:
    post:
      summary: Return server and semantic engine debug information.
      description: |-
        Returns debugging information about the server itself and the
        semantic completer for the current buffer (if there is one).

        This data includes things like the versions of linked-in libraries,
        log file locations, etc.
      produces:
        - application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: A dictionary of debugging information.
          schema:
            type: object
            properties:
              python:
                type: object
                description: |-
                  Debugging information on the Python interpreter in which the
                  server is running.
                properties:
                  executable:
                    type: string
                    description: Python interpreter path.
                  version:
                    type: string
                    description: Python interpreter version.
              clang:
                type: object
                description: Debugging information on Clang.
                properties:
                  has_support:
                    type: boolean
                    description: |-
                      `true` if the ycmd server was built with Clang support,
                      `false` otherwise.
                  version:
                    type: string
                    description: |-
                      if `has_support` is `true`, return the version of Clang.
                      Otherwise, return `null`.
              extra_conf:
                type: object
                description: |-
                  Debugging information on the extra configuration file for the
                  current buffer.
                properties:
                  path:
                    type: string
                    description: |-
                      Path of the found extra configuration file, loaded or not.
                  is_loaded:
                    type: boolean
                    description: |-
                      `true` if the extra configuration file is loaded, `false`
                      otherwise.
              completer:
                description: |-
                  Contains debugging information on the completer for the given
                  filetypes. `null` if no completer is available.
                $ref: "#/definitions/DebugInfoResponse"
          examples:
            application/json:
              python:
                executable: "/path/to/python/interpreter"
                version: "python version"
              clang:
                has_support: true
                version: "clang version"
              extra_conf:
                is_loaded: false
                path: "/path/to/extra/conf"
              completer:
                name: "completer name"
                servers:
                  - name: "server name"
                    is_running: true
                    executable: "/path/to/executable"
                    address: "127.0.0.1"
                    port: 1234
                    pid: 12345
                    logfiles:
                      - "/path/to/stdout/logfile"
                      - "/path/to/stderr/logfile"
                    extras:
                      - description: "description"
                      - value: "value"
                items:
                  - description: "description"
                    value: "value"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/ExceptionResponse"
  /receive_messages:
    post:
      summary: Long poll for asynchronous server messages.
      description: |-
        Return asynchronous messages from the server. This request is
        used by clients in a "long poll" style, and does not return until
        either:

        - A message (or messages) becomes available, in which case a list of
          messages is returned, or
        - a timeout occurs (after 60s), in which case `true` is returned and
          the client should re-send this request, or
        - for some reason the server determined that the client should stop
          sending `receive_messages` requests, in which case `false` is
          returned, and the client should only send the request again when
          something substantial changes such as a new file type is opened, or
          the completer server is manually restarted.

        The following types of event are delivered asynchronously for certain
        filetypes:

        - Status messages to be displayed unobtrusively to the user.
        - Diagnostics (for Java only).

        This message is optional. Clients do not require to implement this
        method, but it is strongly recommended for certain languages to offer
        the best user experience.
      produces:
        application/json
      parameters:
        - name: request_data
          in: body
          description: |-
            The context data, including the current cursor position, and details
            of dirty buffers.
          required: true
          schema:
            $ref: "#/definitions/SimpleRequest"
      responses:
        200:
          description: |-
            Messages are ready, the request timed out, or the request
            is not supported and should not be retried.

            The response may be **one of** `MessagePollResponse` or
            `MessagesList`.
          schema:
            allOf:
            - $ref: '#/definitions/MessagePollResponse'
            - $ref: '#/definitions/MessageList'
          examples:
            application/json:
              - message: 'Initializing: 19% complete'
              - message: 'Initializing: Done.'
              - diagonostics:
                  filepath: '/file'
                  diagnotics:
                  - ranges:
                    - start: { line_num: 10, column_num: 11, filepath: '/file' }
                      end: { line_num: 10, column_num: 20, filepath: '/file' }
                    location: { line_num: 10, column_num: 11, filepath: '/file' }
                    location_extent:
                      start: { line_num: 10, column_num: 11, filepath: '/file' }
                      end: { line_num: 10, column_num: 11, filepath: '/file' }
                    text: Very naughty code!
                    kind: WARNING
                    fixit_available: false
                  - ranges:
                    - start: { line_num: 19, column_num: 11, filepath: '/file' }
                      end: { line_num: 19, column_num: 20, filepath: '/file' }
                    location: { line_num: 19, column_num: 11, filepath: '/file' }
                    location_extent:
                      start: { line_num: 19, column_num: 11, filepath: '/file' }
                      end: { line_num: 19, column_num: 11, filepath: '/file' }
                    text: Very dangerous code!
                    kind: ERROR
                    fixit_available: true
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/ExceptionResponse"