static/openapi.json

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