An example OpenAPI schema for an API

genome_search_def.yaml

openapi: 3.0.0
info:
  title: Species Search API
  description: An API for performing species searches to find species of question
  version: 1.0.0
tags:
  - name: search
    description: Search for genomes/species
paths:
  "/api/genome_search":
    get:
      tags:
        - search
      summary: Search for a set of genome identifiers from a given search string
      description: Here is where a search string could go
      operationId: getGenomeSearch
      parameters:
        - name: query
          in: query
          description: A user submitted string to search for
          example: homo
          required: true
          schema:
            type: string
        - name: division
          in: query
          example: vertebrates
          description: Optional flag used to limit search to a particular sub-set of species
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "400":
          description: Invalid division supplied
servers:
  - url: /
components:
  schemas:
    SearchResponse:
      type: object
      required: 
        - genome_id
      properties:
        genome_id:
          type: string
        reference_genome_id:
          type: string
        common_name:
          type: string
        scientific_name:
          type: string
        assembly_name:
          type: string
        matched_substrings:
          type: object
          required:
            - length
            - offset
            - match
          properties:
            length:
              type: integer
            offset:
              type: integer
            match:
              type: string