static/openapi2.yaml

   1 swagger: "2.0"
   2 info:
   3   description: "OpenAPI for https://codesearch.debian.net/"
   4   version: "1.4.0"
   5   title: "Debian Code Search"
   6   contact:
   7     email: "stapelberg@debian.org"
   8   license:
   9     name: "Apache 2.0"
  10     url: "http://www.apache.org/licenses/LICENSE-2.0.html"
  11 host: "codesearch.debian.net"
  12 basePath: "/api/v1"
  13 schemes:
  14 - "https"
  15 tags:
  16 - name: "search"
  17   description: "Code Search"
  18 parameters:
  19   queryParam:
  20     name: "query"
  21     in: "query"
  22     description: "The search query, for example `who knows...` (literal) or `who knows\\.\\.\\.` (regular expression). See https://codesearch.debian.net/faq for more details about which keywords are supported. The regular expression flavor is RE2, see https://github.com/google/re2/blob/master/doc/syntax.txt"
  23     required: true
  24     type: "string"
  25   matchModeParam:
  26     name: "match_mode"
  27     in: "query"
  28     description: "Whether the query is to be interpreted as a literal (`literal`) instead of as an RE2 regular expression (`regexp`). Literal searches are faster and do not require escaping special characters, regular expression searches are more powerful."
  29     required: false
  30     type: "string"
  31     default: "regexp"
  32     enum:
  33     - "literal"
  34     - "regexp"
  35 paths:
  36   /search:
  37     get:
  38       tags:
  39       - "search"
  40       summary: "Searches through source code"
  41       description: "Performs a search through the full Debian Code Search corpus, blocking until all results are available (might take a few seconds depending on the search query).\n\nSearch results are ordered by their ranking (best results come first)."
  42       operationId: "search"
  43       produces:
  44       - "application/json"
  45       parameters:
  46       - $ref: "#/parameters/queryParam"
  47       - $ref: "#/parameters/matchModeParam"
  48       responses:
  49         "200":
  50           description: "All search results"
  51           schema:
  52             type: "array"
  53             items:
  54               $ref: "#/definitions/SearchResult"
  55         "403":
  56           description: "The x-dcs-apikey header was either not set at all, or contained an invalid (no longer valid?) API key. Please see https://codesearch.debian.net/apikeys/ for obtaining a key."
  57       security:
  58       - api_key: []
  59   /searchperpackage:
  60     get:
  61       tags:
  62       - "search"
  63       summary: "Like /search, but aggregates per package"
  64       description: "The search results are currently sorted arbitrarily, but we intend to sort them by ranking eventually: https://github.com/Debian/dcs/blob/51338e934eb7ee18d00c5c18531c0790a83cb698/cmd/dcs-web/querymanager.go#L719"
  65       operationId: "searchperpackage"
  66       produces:
  67       - "application/json"
  68       parameters:
  69       - $ref: "#/parameters/queryParam"
  70       - $ref: "#/parameters/matchModeParam"
  71       responses:
  72         "200":
  73           description: "All search results"
  74           schema:
  75             type: "array"
  76             items:
  77               $ref: "#/definitions/PackageSearchResult"
  78         "403":
  79           description: "The x-dcs-apikey header was either not set at all, or contained an invalid (no longer valid?) API key. Please see https://codesearch.debian.net/apikeys/ for obtaining a key."
  80       security:
  81       - api_key: []
  82 securityDefinitions:
  83   api_key:
  84     type: "apiKey"
  85     name: "x-dcs-apikey"
  86     in: "header"
  87 definitions:
  88   SearchResult:
  89     type: "object"
  90     required:
  91     - "package"
  92     - "path"
  93     - "line"
  94     - "context"
  95     description: "A search result matching the specified query. You can use sources.debian.org to view the file contents. See https://github.com/Debian/dcs/blob/master/cmd/dcs-web/show/show.go for how to construct a sources.debian.org URL from a search result."
  96     properties:
  97       package:
  98         type: "string"
  99         description: "The Debian source package containing this search result, including the full Debian version number."
 100         example: "i3-wm_4.18-1"
 101       path:
 102         type: "string"
 103         example: "i3bar/src/xcb.c"
 104         description: "Path to the file containing the this search result, starting with `package`."
 105       line:
 106         type: "integer"
 107         format: "uint32"
 108         example: 1313
 109         description: "Line number containing the search result."
 110       context_before:
 111         type: "array"
 112         items:
 113           type: "string"
 114         description: "Up to 2 full lines before the search result (see `context`)."
 115         example:
 116           - "    } else {"
 117           - "        cursor = xcb_generate_id(xcb_connection);"
 118       context:
 119         type: "string"
 120         example: "        i3Font cursor_font = load_font(\"cursor\", false);"
 121         description: "The full line containing the search result."
 122       context_after:
 123         type: "array"
 124         items:
 125           type: "string"
 126         description: "Up to 2 full lines after the search result (see `context`)."
 127         example:
 128           - "        xcb_create_glyph_cursor("
 129           - "            xcb_connection,"
 130   PackageSearchResult:
 131     type: "object"
 132     required:
 133     - "package"
 134     - "results"
 135     properties:
 136       package:
 137         type: "string"
 138         example: "i3-wm_4.18-1"
 139         description: "The Debian source package for which up to 2 search results have been aggregated in `results`."
 140       results:
 141         type: "array"
 142         items:
 143           $ref: "#/definitions/SearchResult"
 144 externalDocs:
 145   description: "Get a Debian Code Search API key"
 146   url: "https://codesearch.debian.net/apikeys/"