openapi: 3.1.0
info:
  title: RubyGems Search API
  description: >-
    The RubyGems Search API allows developers to search for gems on
    RubyGems.org by matching a query string against gem names and
    descriptions. It returns an array of matching active gems with their
    metadata, making it useful for building gem discovery tools, IDE
    integrations, and dependency resolution utilities. The search endpoint
    supports pagination for handling large result sets.
  version: '1.0'
  contact:
    name: RubyGems.org Support
    url: https://help.rubygems.org
  termsOfService: https://rubygems.org/pages/about
externalDocs:
  description: RubyGems.org API Documentation
  url: https://guides.rubygems.org/rubygems-org-api/
servers:
  - url: https://rubygems.org/api/v1
    description: Production Server
tags:
  - name: Search
    description: >-
      Endpoints for searching gems on RubyGems.org by name and description.
paths:
  /search.json:
    get:
      operationId: searchGems
      summary: Search For Gems
      description: >-
        Submit a search query to RubyGems.org for active gems. Returns an
        array of gem objects that match the query string against gem names
        and descriptions. Results are paginated with 30 gems per page.
      tags:
        - Search
      security: []
      parameters:
        - name: query
          in: query
          description: >-
            The search query string to match against gem names and
            descriptions.
          required: true
          schema:
            type: string
          example: json parser
        - name: page
          in: query
          description: >-
            Page number for paginated results. Each page returns up to
            30 matching gems.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: Successful response with array of matching gems
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Gem'
components:
  schemas:
    Gem:
      type: object
      description: A Ruby gem hosted on RubyGems.org
      properties:
        name:
          type: string
          description: The name of the gem
        downloads:
          type: integer
          description: Total number of downloads for this gem
        version:
          type: string
          description: The current (latest) version number
        version_created_at:
          type: string
          format: date-time
          description: Timestamp when the current version was created
        version_downloads:
          type: integer
          description: Download count for the current version
        platform:
          type: string
          description: The platform of the gem (e.g., ruby, java)
        authors:
          type: string
          description: Comma-separated list of gem authors
        info:
          type: string
          description: Short description of the gem
        licenses:
          type: array
          items:
            type: string
          description: List of licenses for the gem
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Additional metadata key-value pairs
        sha:
          type: string
          description: SHA-256 checksum of the gem file
        project_uri:
          type: string
          format: uri
          description: URI to the gem project page on RubyGems.org
        gem_uri:
          type: string
          format: uri
          description: URI to download the gem file
        homepage_uri:
          type: string
          format: uri
          description: URI to the gem homepage
        documentation_uri:
          type: string
          format: uri
          description: URI to the gem documentation
        source_code_uri:
          type: string
          format: uri
          description: URI to the gem source code
        bug_tracker_uri:
          type: string
          format: uri
          description: URI to the gem bug tracker
        changelog_uri:
          type: string
          format: uri
          description: URI to the gem changelog
        dependencies:
          type: object
          properties:
            development:
              type: array
              items:
                $ref: '#/components/schemas/Dependency'
              description: Development dependencies
            runtime:
              type: array
              items:
                $ref: '#/components/schemas/Dependency'
              description: Runtime dependencies
          description: Gem dependency information
    Dependency:
      type: object
      description: A gem dependency
      properties:
        name:
          type: string
          description: Name of the dependency gem
        requirements:
          type: string
          description: Version requirements string