searcherside/assets/api/searcherside_v1.yaml

openapi: 3.1.0
info:
  title: Searcherside
  license:
    name: MIT
    url: https://code.icb4dc0.de/prskr/searcherside/src/branch/main/LICENSE
  version: 0.1.0
servers:
  - url: http://localhost:3000/api/v1
tags:
  - name: index
    description: Interact with indices
  - name: search
    description: Search in indices
paths:
  /site/{siteId}/index/{indexName}:
    put:
      tags:
        - index
      summary: Create a new index by uploading an archive of all documents to index
      operationId: upsertIndexForSite
      parameters:
        - name: siteId
          in: path
          description: ID of the site for which to upsert a new index
          required: true
          schema:
            type: string
            format: uuid
        - name: indexName
          in: path
          description: Name of the index to create
          required: true
          examples:
            Writerside:
              description: |
                Writerside index of the format <module>/<instance>
              value: web/g
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  format: binary
      responses:
        '202':
          description: Accepted upload of file

  /site/{siteId}/preview-search/{indexName}:
    get:
      tags:
        - search
      summary: Search in the latest index version of the specified site
      security:
        - jwtAuth: []
      operationId: previewSearch
      parameters:
        - name: siteId
          in: path
          description: ID of the site for which to upsert a new index
          required: true
          schema:
            type: string
            format: uuid
        - name: indexName
          in: path
          description: Name of the index to create
          required: true
          examples:
            Writerside:
              description: |
                Writerside index of the format <module>/<instance>
              value: web/g
          schema:
            type: string
        - name: query
          in: query
          description: Search query
          required: true
          schema:
            type: string
        - name: isExactSearch
          in: query
          description: Whether only exact matches should be considered
          required: false
          schema:
            type: boolean
        - name: maxHits
          in: query
          description: Maximum number of items to return
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Successfully searched in index
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"

components:
  schemas:
    MatchLevel:
      type: string
      enum: [none, full]
    HighlightResult:
      type: object
      additionalProperties:
        type: object
        properties:
          value:
            type: string
          matchLevel:
            $ref: "#/components/schemas/MatchLevel"
          fullyHighlighted:
            type: bool
          matchedWords:
            type: array
            items:
              type: string
    SearchHit:
      type: object
      properties:
        objectID:
          type: string
        mainTitle:
          type: string
        pageTitle:
          type: string
        url:
          type: string
        breadcrumbs:
          type: string
        _snippetResult:
          type: object
          properties:
            content:
              type: object
              properties:
                value:
                  type: string
                matchLevel:
                  $ref: "#/components/schemas/MatchLevel"
        _highlightResult:
          $ref: "#/components/schemas/HighlightResult"
    SearchResponse:
      type: object
      properties:
        hits:
          type: array
          items:
            $ref: "#/components/schemas/SearchHit"

  securitySchemes:
    jwtAuth:
      type: apiKey
      name: api_key
      in: header