static/openapi.yaml

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