A demonstrative swagger.yaml for the Metabolomics Workbench REST API

swagger.yaml

openapi: 3.0.0
info:
  title: Metabolomics Workbench REST API
  version: "1.0.0"
  description: |
    The Metabolomics WorkBench REST service enables access to a variety of data (including metabolite structures, study metadata and experimental results) using HTTP requests. These requests may be carried out using a web browser or may be embedded in 3rd party applications or scripts to enable programmatic access. Most modern programming languages including PHP, Perl, Python, Java and Javascript have the capability to create HTTP request and interact with datasets such as this REST service.
  license:
    name: Metabolomics Workbench Terms of Use
    url: https://www.metabolomicsworkbench.org/about/termsofuse.php
  contact:
    url: https://www.metabolomicsworkbench.org/about/contact.php
servers:
  - description: Metabolomics Workbench
    url: https://www.metabolomicsworkbench.org/rest
paths:
  /study/study_id/ST/available:
    get:
      description: Fetch summary information for all studies
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    project_id:
                      type: string
                    study_id:
                      type: string
                    analysis_id:
                      type: string

  /study/study_id/{study_id}/summary:
    get:
      description: Fetch summary information for a study
      parameters:
      - in: path
        name: study_id
        description: The unique study identifier
        schema:
          type: string
          pattern: '^ST\d*$'
        example: ST000001
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudySummary'

  /protein/gene_id/{gene_id}/all/:
    get:
      description: Fetch all protein fields from Entrez gene id
      parameters:
      - in: path
        name: gene_id
        description: The unique study identifier
        schema:
          type: string
        example: '19'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  gene_id:
                    type: string
                    description: Entrez Gene ID
                  mgp_id:
                    type: string
                    description: MGP ID
                  gene_name:
                    type: string
                    description: Verbose gene name
                  gene_symbol:
                    type: string
                    description: Entrez Gene Symbol
                  taxid:
                    type: string
                    description: Taxonomy taxon ID
                  species:
                    type: string
                    description: Species name
                  species_long:
                    type: string
                    description: Species official name
                  mrna_id:
                    type: string
                    description: ID of the MRNA
                  refseq_id:
                    type: string
                    description: ID on refseq
                  protein_gi:
                    type: string
                    description: ID on GI
                  uniprot_id:
                    type: string
                    description: ID on GI
                  protein_entry:
                    type: string
                    description: Protein term
                  protein_name:
                    type: string
                    description: Verbose protein name
                  seqlength:
                    type: string
                    description: Length of the sequence
                  seq:
                    type: string
                    description: The protein sequence itself
          x-responseValueType:
          - x-path: gene_id
            x-valueType: https://identifiers.org/ncbigene
          - x-path: gene_symbol
            x-valueType: https://identifiers.org/genecards
          - x-path: tax_id
            x-valueType: https://identifiers.org/taxonomy
          - x-path: mrna_id
            x-valueType: https://www.ncbi.nlm.nih.gov/nuccore
          - x-path: refseq_id
            x-valueType: https://www.ncbi.nlm.nih.gov/protein
          - x-path: uniprot_id
            x-valueType: https://identifiers.org/uniprot

components:
  schemas:
    StudySummary:
      description: Summary information about a study
      type: object
      properties:
        study_id:
          type: string
          description: A unique identifier for this study
        study_title:
          type: string
        study_type:
          type: string
          description: The type of treatment used in the study
        institute:
          type: string
          description: The institution that performed the study
        department:
          type: string
          description: The department in the institute that performed the study
        last_name:
          type: string
          description: The last name of the PI responsible for the study
        first_name:
          type: string
          description: The first name of the PI responsible for the study
        email:
          type: string
          description: The email to contact for information about the study
        submit_date:
          type: string
          description: The date this study was submitted to metabolomics workbench
        study_summary:
          type: string
          description: A detailed summary describing the study
        subject_species:
          type: string
          description: The species of the subject of the study