static/openapi2.json

   1 {
   2   "swagger": "2.0",
   3   "info": {
   4     "description": "OpenAPI for https://codesearch.debian.net/",
   5     "version": "1.4.0",
   6     "title": "Debian Code Search",
   7     "contact": {
   8       "email": "stapelberg@debian.org"
   9     },
  10     "license": {
  11       "name": "Apache 2.0",
  12       "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  13     }
  14   },
  15   "host": "codesearch.debian.net",
  16   "basePath": "/api/v1",
  17   "schemes": [
  18     "https"
  19   ],
  20   "tags": [
  21     {
  22       "name": "search",
  23       "description": "Code Search"
  24     }
  25   ],
  26   "parameters": {
  27     "queryParam": {
  28       "name": "query",
  29       "in": "query",
  30       "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",
  31       "required": true,
  32       "type": "string"
  33     },
  34     "matchModeParam": {
  35       "name": "match_mode",
  36       "in": "query",
  37       "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.",
  38       "required": false,
  39       "type": "string",
  40       "default": "regexp",
  41       "enum": [
  42         "literal",
  43         "regexp"
  44       ]
  45     }
  46   },
  47   "paths": {
  48     "/search": {
  49       "get": {
  50         "tags": [
  51           "search"
  52         ],
  53         "summary": "Searches through source code",
  54         "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).",
  55         "operationId": "search",
  56         "produces": [
  57           "application/json"
  58         ],
  59         "parameters": [
  60           {
  61             "$ref": "#/parameters/queryParam"
  62           },
  63           {
  64             "$ref": "#/parameters/matchModeParam"
  65           }
  66         ],
  67         "responses": {
  68           "200": {
  69             "description": "All search results",
  70             "schema": {
  71               "type": "array",
  72               "items": {
  73                 "$ref": "#/definitions/SearchResult"
  74               }
  75             }
  76           },
  77           "403": {
  78             "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."
  79           }
  80         },
  81         "security": [
  82           {
  83             "api_key": []
  84           }
  85         ]
  86       }
  87     },
  88     "/searchperpackage": {
  89       "get": {
  90         "tags": [
  91           "search"
  92         ],
  93         "summary": "Like /search, but aggregates per package",
  94         "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",
  95         "operationId": "searchperpackage",
  96         "produces": [
  97           "application/json"
  98         ],
  99         "parameters": [
 100           {
 101             "$ref": "#/parameters/queryParam"
 102           },
 103           {
 104             "$ref": "#/parameters/matchModeParam"
 105           }
 106         ],
 107         "responses": {
 108           "200": {
 109             "description": "All search results",
 110             "schema": {
 111               "type": "array",
 112               "items": {
 113                 "$ref": "#/definitions/PackageSearchResult"
 114               }
 115             }
 116           },
 117           "403": {
 118             "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."
 119           }
 120         },
 121         "security": [
 122           {
 123             "api_key": []
 124           }
 125         ]
 126       }
 127     }
 128   },
 129   "securityDefinitions": {
 130     "api_key": {
 131       "type": "apiKey",
 132       "name": "x-dcs-apikey",
 133       "in": "header"
 134     }
 135   },
 136   "definitions": {
 137     "SearchResult": {
 138       "type": "object",
 139       "required": [
 140         "package",
 141         "path",
 142         "line",
 143         "context"
 144       ],
 145       "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.",
 146       "properties": {
 147         "package": {
 148           "type": "string",
 149           "description": "The Debian source package containing this search result, including the full Debian version number.",
 150           "example": "i3-wm_4.18-1"
 151         },
 152         "path": {
 153           "type": "string",
 154           "example": "i3bar/src/xcb.c",
 155           "description": "Path to the file containing the this search result, starting with `package`."
 156         },
 157         "line": {
 158           "type": "integer",
 159           "format": "uint32",
 160           "example": 1313,
 161           "description": "Line number containing the search result."
 162         },
 163         "context_before": {
 164           "type": "array",
 165           "items": {
 166             "type": "string"
 167           },
 168           "description": "Up to 2 full lines before the search result (see `context`).",
 169           "example": [
 170             "    } else {",
 171             "        cursor = xcb_generate_id(xcb_connection);"
 172           ]
 173         },
 174         "context": {
 175           "type": "string",
 176           "example": "        i3Font cursor_font = load_font(\"cursor\", false);",
 177           "description": "The full line containing the search result."
 178         },
 179         "context_after": {
 180           "type": "array",
 181           "items": {
 182             "type": "string"
 183           },
 184           "description": "Up to 2 full lines after the search result (see `context`).",
 185           "example": [
 186             "        xcb_create_glyph_cursor(",
 187             "            xcb_connection,"
 188           ]
 189         }
 190       }
 191     },
 192     "PackageSearchResult": {
 193       "type": "object",
 194       "required": [
 195         "package",
 196         "results"
 197       ],
 198       "properties": {
 199         "package": {
 200           "type": "string",
 201           "example": "i3-wm_4.18-1",
 202           "description": "The Debian source package for which up to 2 search results have been aggregated in `results`."
 203         },
 204         "results": {
 205           "type": "array",
 206           "items": {
 207             "$ref": "#/definitions/SearchResult"
 208           }
 209         }
 210       }
 211     }
 212   },
 213   "externalDocs": {
 214     "description": "Get a Debian Code Search API key",
 215     "url": "https://codesearch.debian.net/apikeys/"
 216   }
 217 }