openapi-user.yaml

openapi: 3.0.3
info:
  title: Fess - User API
  description: |-
    This is a Fess Server based on the OpenAPI 3.0 specification.  
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 14.8.0
externalDocs:
  description: API Documentation
  url: https://fess.codelibs.org/14.8/api/
servers:
  - url: http://localhost:8080/api/v1
tags:
  - name: search
    description: Search operations
  - name: popularword
    description: Popular word operations
  - name: monitor
    description: Monitoring operations
  - name: suggest
    description: Suggest operations
  - name: favorite
    description: Favorite operations
paths:
  /documents:
    get:
      tags:
        - search
      summary: Finds documents by query
      description: Finds documents by search conditions
      operationId: searchDocuments
      parameters:
        - name: q
          in: query
          description: Search words
          required: false
          schema:
            type: string
            example: Fess
        - name: start
          in: query
          description: Start position
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            default: 0
            example: 0
        - name: offset
          in: query
          description: Offset from a start position
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            default: 0
            example: 0
        - name: num
          in: query
          description: The number of returned documents as a search result
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            maximum: 100
            exclusiveMaximum: false
            default: 20
            example: 20
        - name: sort
          in: query
          description: Sorted field name
          required: false
          schema:
            type: string
            example: score
        - name: fields.label
          in: query
          description: Filtered label name
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [name]
        - name: facet.field
          in: query
          description: Facet field name
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [label]
        - name: facet.query
          in: query
          description: Facet query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: ["timestamp:[now/d-1d TO *]"]
        - name: facet.size
          in: query
          description: Item size in facets returned by facet.field
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            default: 10
            example: 10
        - name: facet.minDocCount
          in: query
          description: Minumum document size in facets
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            default: 0
            example: 0
        - name: geo.location.point
          in: query
          description: Latitude and Longitude for Geo search
          required: false
          schema:
            type: string
            example: 35.0,139.0
        - name: geo.location.distance
          in: query
          description: Distance for Geo search
          required: false
          schema:
            type: string
            example: 10km
        - name: lang
          in: query
          description: Language
          required: false
          schema:
            type: string
            example: en
        - name: preference
          in: query
          description: String to specify a shard for searching
          required: false
          schema:
            type: string
            example: abc
        - name: callback
          in: query
          description: Callback name for using JSONP
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  q:
                    type: string
                    example: Fess
                  query_id:
                    type: string
                    example: bd60f9579a494dfd8c03db7c8aa905b0
                  exec_time:
                    type: number
                    example: 0.21
                  query_time:
                    type: integer
                    format: int64
                    example: 0
                  page_size:
                    type: integer
                    example: 20
                  page_number:
                    type: integer
                    example: 1
                  record_count:
                    type: integer
                    format: int64
                    example: 31625
                  page_count:
                    type: integer
                    example: 1
                  highlight_params:
                    type: string
                    example: "&hq=n2sm&hq=Fess"
                  next_page:
                    type: boolean
                    example: true
                  prev_page:
                    type: boolean
                    example: false
                  start_record_number:
                    type: integer
                    example: 1
                  end_record_number:
                    type: integer
                    example: 20
                  page_numbers:
                    type: array
                    items:
                      type: string
                    example: ["1", "2", "3", "4", "5"]
                  partial:
                    type: boolean
                    example: false
                  search_query:
                    type: string
                    example: "(Fess OR n2sm)"
                  requested_time:
                    type: integer
                    format: int64
                    example: 1507822131845
                  related_query:
                    type: array
                    items:
                      type: string
                    example: ["aaa"]
                  related_contents:
                    type: array
                    items:
                      type: string
                    example: []
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        filetype:
                          type: string
                          example: html
                        title:
                          type: string
                          example: "Open Source Enterprise Search Server: Fess — Fess 11.0 documentation"
                        content_title:
                          type: string
                          example: "Open Source Enterprise Search Server: Fess — Fe..."
                        digest:
                          type: string
                          example: "Docs » Open Source Enterprise Search Server: Fess Commercial Support Open Source Enterprise Search Server: Fess What is Fess ? Fess is very powerful and easily deployable Enterprise Search Server. ..."
                        host:
                          type: string
                          format: hostname
                          example: "fess.codelibs.org"
                        last_modified:
                          type: string
                          format: date-time
                          example: "2017-10-09T22:28:56.000Z"
                        content_length:
                          type: string
                          example: "29624"
                        timestamp:
                          type: string
                          format: date-time
                          example: "2017-10-09T22:28:56.000Z"
                        url_link:
                          type: string
                          example: "https://fess.codelibs.org/"
                        created:
                          type: string
                          format: date-time
                          example: "2017-10-10T15:00:48.609Z"
                        site_path:
                          type: string
                          example: "fess.codelibs.org/"
                        doc_id:
                          type: string
                          example: "e79fbfdfb09d4bffb58ec230c68f6f7e"
                        url:
                          type: string
                          format: uri
                          example: "https://fess.codelibs.org/"
                        content_description:
                          type: string
                          example: "Enterprise Search Server: <strong>Fess</strong> Commercial Support Open...Search Server: <strong>Fess</strong> What is <strong>Fess</strong> ? <strong>Fess</strong> is very powerful...You can install and run <strong>Fess</strong> quickly on any platforms...Java runtime environment. <strong>Fess</strong> is provided under Apache...Apache license. Demo <strong>Fess</strong> is Elasticsearch-based search"
                        site:
                          type: string
                          example: "fess.codelibs.org/"
                        boost:
                          type: string
                          example: "10.0"
                        mimetype:
                          type: string
                          example: "text/html"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /documents/all:
    get:
      tags:
        - search
      summary: Finds all documents by query
      description: Finds all documents by search conditions
      operationId: searchAllDocuments
      parameters:
        - name: q
          in: query
          description: Search words
          required: false
          schema:
            type: string
            example: Fess
        - name: num
          in: query
          description: The number of returned documents as a search result
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            maximum: 100
            exclusiveMaximum: false
            default: 20
            example: 20
        - name: sort
          in: query
          description: Sorted field name
          required: false
          schema:
            type: string
            example: score
      responses:
        '200':
          description: Successful operation
          content:
            application/x-ndjson:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /labels:
    get:
      tags:
        - search
      summary: List labels
      description: Returns available labels
      operationId: listLabels
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  record_count:
                    type: integer
                    example: 9
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          example: AWS
                        value:
                          type: string
                          example: aws
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /favorites:
    get:
      tags:
        - favorite
      summary: List favorites
      description: Returns favorited document IDs
      operationId: listFavorites
      parameters:
        - name: queryId
          in: query
          description: Query ID where the document is contained
          required: true
          schema:
            type: string
            example: queryid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  record_count:
                    type: integer
                    example: 9
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        doc_id:
                          type: string
                          example: "e79fbfdfb09d4bffb58ec230c68f6f7e"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /documents/{docId}/favorite:
    post:
      tags:
        - favorite
      summary: Set a favorite mark
      description: Set a favorite mark to the document
      operationId: setFavorite
      parameters:
        - name: docId
          in: path
          description: Document ID to be favorited
          required: true
          schema:
            type: string
            example: documentid
        - name: queryId
          in: query
          description: Query ID where the document is contained
          required: true
          schema:
            type: string
            example: queryid
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /popular-words:
    get:
      tags:
        - popularword
      summary: List popular words
      description: Returns available labels
      operationId: listPopularWords
      parameters:
        - name: seed
          in: query
          description: Random seed to return popular words
          required: false
          schema:
            type: string
            example: 123
        - name: label
          in: query
          description: Filtered label name
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [label]
        - name: field
          in: query
          description: Field name to generate suggest words
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [python]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  record_count:
                    type: integer
                    example: 9
                  data:
                    type: array
                    items:
                      type: string
                    example: ["python"]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
          
  /health:
    get:
      tags:
        - monitor
      summary: Check a server status
      description: Returns status
      operationId: ping
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: green
                      timed_out:
                        type: boolean
                        example: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: green
                      timed_out:
                        type: boolean
                        example: false

  /suggest-words:
    get:
      tags:
        - suggest
      summary: Finds suggest words
      description: Returns words for suggest
      operationId: findSuggestWords
      parameters:
        - name: q
          in: query
          description: Inputting characters for search
          required: true
          schema:
            type: string
            example: fe
        - name: num
          in: query
          description: The number of suggest words
          required: false
          schema:
            type: integer
            minimum: 0
            exclusiveMinimum: false
            example: 10
            default: 10
        - name: label
          in: query
          description: Filtered label name
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [label]
        - name: field
          in: query
          description: Field name to generate suggest words
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [python]
        - name: lang
          in: query
          description: Target language
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example: [en]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  query_time:
                    type: integer
                    format: int64
                    example: 18
                  record_count:
                    type: integer
                    example: 355
                  page_size:
                    type: integer
                    example: 10
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          example: fess
                        labels:
                          type: array
                          items:
                            type: string
                          example: [java, python]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Page not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: string
          example: "bd6b0bd6-0144-40bc-9567-c5751dd8eecb"
        message:
          type: string
          example: "This is an error message."