openapi: 3.0.3
info:
  title: RAE API
  description: |
    API no oficial para consultar el diccionario de la Real Academia Española.
    Permite obtener definiciones, conjugaciones, etimología y más.
  version: "1.0.0"
  contact:
    name: RAE API Organization
    url: https://rae-api.com
servers:
  - url: https://rae-api.com

paths:
  /api/words/{palabra}:
    get:
      summary: Obtener información de una palabra
      description: Devuelve definiciones, origen y conjugaciones verbales (si aplica) de una palabra.
      parameters:
        - name: palabra
          in: path
          required: true
          description: Palabra a consultar
          schema:
            type: string
      responses:
        '200':
          description: Éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WordEntryResponse'
        '404':
          description: NOT_FOUND
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/random:
    get:
      summary: Obtener una palabra aleatoria
      description: Devuelve una palabra aleatoria del diccionario.
      parameters:
        - name: min_length
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
          description: Longitud mínima de la palabra
        - name: max_length
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
          description: Longitud máxima de la palabra
      responses:
        '200':
          description: Éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WordOnlyResponse'

  /api/daily:
    get:
      summary: Obtener la palabra del día
      description: Devuelve la palabra del día.
      responses:
        '200':
          description: Éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WordOnlyResponse'

components:
  schemas:
    WordEntryResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/WordEntry'
    WordOnlyResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          type: object
          properties:
            word:
              type: string
    WordEntry:
      type: object
      properties:
        word:
          type: string
        meanings:
          type: array
          items:
            $ref: '#/components/schemas/Meaning'
    Meaning:
      type: object
      properties:
        origin:
          $ref: '#/components/schemas/Origin'
        senses:
          type: array
          items:
            $ref: '#/components/schemas/Definition'
        conjugations:
          $ref: '#/components/schemas/Conjugations'
    Origin:
      type: object
      properties:
        raw:
          type: string
        type:
          type: string
        voice:
          type: string
        text:
          type: string
    Definition:
      type: object
      properties:
        raw:
          type: string
        meaning_number:
          type: integer
        category:
          type: string
          enum: [noun, verb, adjective, adverb, pronoun, article, preposition, conjunction, interjection]
        verb_category:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        article:
          $ref: '#/components/schemas/Article'
        usage:
          type: string
          enum: [common, rare, outdated, colloquial, obsolete, unknown]
        description:
          type: string
        synonyms:
          type: array
          items:
            type: string
        antonyms:
          type: array
          items:
            type: string
    Article:
      type: object
      properties:
        category:
          type: string
          enum: [definite, indefinite, neuter]
        gender:
          type: string
          enum: [masculine, feminine, masculine_and_feminine, unknown]
    Conjugations:
      type: object
      properties:
        non_personal:
          $ref: '#/components/schemas/ConjugationNonPersonal'
        indicative:
          $ref: '#/components/schemas/ConjugationIndicative'
        subjunctive:
          $ref: '#/components/schemas/ConjugationSubjunctive'
        imperative:
          $ref: '#/components/schemas/ConjugationImperative'
    ConjugationNonPersonal:
      type: object
      properties:
        infinitive:
          type: string
        participle:
          type: string
        gerund:
          type: string
        compound_infinitive:
          type: string
        compound_gerund:
          type: string
    ConjugationIndicative:
      type: object
      properties:
        present:
          $ref: '#/components/schemas/Conjugation'
        present_perfect:
          $ref: '#/components/schemas/Conjugation'
        imperfect:
          $ref: '#/components/schemas/Conjugation'
        past_perfect:
          $ref: '#/components/schemas/Conjugation'
        preterite:
          $ref: '#/components/schemas/Conjugation'
        past_anterior:
          $ref: '#/components/schemas/Conjugation'
        future:
          $ref: '#/components/schemas/Conjugation'
        future_perfect:
          $ref: '#/components/schemas/Conjugation'
        conditional:
          $ref: '#/components/schemas/Conjugation'
        conditional_perfect:
          $ref: '#/components/schemas/Conjugation'
    ConjugationSubjunctive:
      type: object
      properties:
        present:
          $ref: '#/components/schemas/Conjugation'
        present_perfect:
          $ref: '#/components/schemas/Conjugation'
        imperfect:
          $ref: '#/components/schemas/Conjugation'
        past_perfect:
          $ref: '#/components/schemas/Conjugation'
        future:
          $ref: '#/components/schemas/Conjugation'
        future_perfect:
          $ref: '#/components/schemas/Conjugation'
    ConjugationImperative:
      type: object
      properties:
        singular_second_person:
          type: string
        singular_formal_second_person:
          type: string
        plural_second_person:
          type: string
        plural_formal_second_person:
          type: string
    Conjugation:
      type: object
      properties:
        singular_first_person:
          type: string
        singular_second_person:
          type: string
        singular_formal_second_person:
          type: string
        singular_third_person:
          type: string
        plural_first_person:
          type: string
        plural_second_person:
          type: string
        plural_formal_second_person:
          type: string
        plural_third_person:
          type: string
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
          example: NOT_FOUND