openapi.yaml

openapi: 3.1.0
info:
  contact:
    email: zelcon@zelcon.net
    name: Zelly Snyder
  description: Get a random Wikipedia article under a category
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  title: WikiDice
  version: 1.0.0
servers:
- description: Production server
  url: https://wikidice.zelcon.net/api/
paths:
  /random/{category}:
    get:
      description: Get a random article from Wikipedia under a category
      operationId: get_random_article
      parameters:
      - description: "Category to search under (recursively, including subcategories)"
        explode: false
        in: path
        name: category
        required: true
        schema:
          type: string
        style: simple
      - description: |
          Maximum depth (recursive subcategories) to search for articles
        explode: true
        in: query
        name: depth
        required: false
        schema:
          default: 5
          maximum: 100
          minimum: 0
          type: integer
        style: form
      - allowEmptyValue: false
        description: |
          Wikipedia language name such as en, de, etc. For examples, see:
          https://en.wikipedia.org/wiki/List_of_Wikipedias
        explode: true
        in: query
        name: language
        required: false
        schema:
          default: en
          type: string
        style: form
      responses:
        "302":
          description: Found
          headers:
            Location:
              description: Redirect location
              explode: false
              schema:
                type: string
              style: simple
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      summary: Pick a random article under a category
  /random_with_derivation/{category}:
    get:
      description: |
        Get a random article from Wikipedia under a category, but also return
        the category path that was traversed to get to the article.
      operationId: get_random_article_with_derivation
      parameters:
      - description: "Category to search under (recursively, including subcategories)"
        explode: false
        in: path
        name: category
        required: true
        schema:
          type: string
        style: simple
      - description: |
          Maximum depth (recursive subcategories) to search for articles
        explode: true
        in: query
        name: depth
        required: false
        schema:
          default: 5
          maximum: 100
          minimum: 0
          type: integer
        style: form
      - allowEmptyValue: false
        description: |
          Wikipedia language name such as en, de, etc. For examples, see:
          https://en.wikipedia.org/wiki/List_of_Wikipedias
        explode: true
        in: query
        name: language
        required: false
        schema:
          default: en
          example: en
          type: string
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RandomArticleWithDerivation'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      summary: "Get a random article, but with details"
  /autocomplete:
    get:
      description: Prefix search for categories
      operationId: category_autocomplete
      parameters:
      - description: Prefix to search for
        explode: true
        in: query
        name: prefix
        required: true
        schema:
          type: string
        style: form
      - allowEmptyValue: false
        description: |
          Wikipedia language name such as en, de, etc. For examples, see:
          https://en.wikipedia.org/wiki/List_of_Wikipedias
        explode: true
        in: query
        name: language
        required: false
        schema:
          default: en
          example: en
          type: string
        style: form
      - description: |
          Maximum number of results to return
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 10
          maximum: 100
          minimum: 1
          type: integer
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                - Computer science
                - Computer science-related professional associations
                - Computer science articles by importance
                - Computer science articles by quality
                - Computer science articles needing attention
                - Computer science articles needing expert attention
                - Computer science articles without infoboxes
                - Computer science award winners
                - Computer science awards
                - Computer science awards navigational boxes
                items:
                  type: string
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      summary: Autocompletion search for category names
components:
  schemas:
    Error:
      properties:
        error:
          description: Error message
          example: Category not found
          title: error
          type: string
        internal_code:
          description: Internal error code
          example: "404"
          title: internal_code
          type: string
          nullable: true
      title: Error
    RandomArticleWithDerivation:
      example:
        derivation:
        - Physics
        - Subfields of physics
        - Computational physics
        - Lattice models
        article: 24535618
      properties:
        article:
          description: Page ID
          title: article
          type: integer
        derivation:
          description: |
            Derivation path to article (which categories were traversed to find
            it)
          example:
          - Physics
          - Concepts in physics
          items:
            type: string
          type: array
      title: RandomArticleWithDerivation