openapi: 3.0.1
info:
  title: Mathoid
  description: Renders TeX to SVG and MathML using MathJax
  termsOfService: https://wikimediafoundation.org/wiki/Terms_of_Use
  contact:
    name: the Wikimedia Services team
    url: http://mediawiki.org/wiki/Services
  license:
    name: Apache2
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 0.2.8
# TODO: uncomment once we have support for removing
# trailing slashes in service-checker
#servers:
#  - url: /
paths:
  # from routes/root.js
  /robots.txt:
    get:
      tags:
        - Root
        - Robots
      description: Gets robots.txt
      responses:
        200:
          description: OK
          content: {}
      x-monitor: false
  /:
    get:
      tags:
        - Root
      description: The root service end-point
      responses:
        200:
          description: OK
          content: {}
      x-amples:
        - title: spec from root
          request:
            query:
              spec: true
          response:
            status: 200
    post:
      tags:
        - Render
      description: Converts TeX to MathML, SVG, PNG and IMG
      responses:
        200:
          description: OK
          content: {}
        400:
          description: invalid input
          content: {}
      x-amples:
        # from routes/info.js
        - title: mass-energy equivalence (json)
          request:
            body:
              q: E=mc^2
          response:
            status: 200
            body:
              log: success
              success: true
              svg: /.+/
              mml: /.+/
  /_info:
    get:
      tags:
        - Service information
      description: Gets information about the service
      responses:
        200:
          description: OK
          content: {}
      x-amples:
        # from routes/mathoid.js
        - title: retrieve service info
          request: {}
          response:
            status: 200
            headers:
              content-type: application/json
            body:
              name: /.+/
              description: /.+/
              version: /.+/
              home: /.+/
  /{format}/:
    post:
      tags:
        - Render
      description: Converts TeX to SVG, PNG or MathML depending on the parameter format.
        The special format 'texvcinfo' returns information about the input without
        to render anything.
      parameters:
        - name: format
          in: path
          description: output type
          required: true
          schema:
            type: string
            enum:
              - texvcinfo
              - speech
              - mml
              - svg
              - png
              - json
              - complete
      responses:
        200:
          description: OK
          content: {}
        400:
          description: invalid input
          content: {}
      x-amples:
        - title: mass-energy equivalence (complete)
          request:
            params:
              format: complete
            body:
              q: E=mc^2
          response:
            status: 200
            headers:
              content-type: /application\/json/
            body:
              success: true
              svg:
                headers:
                  content-type: image/svg+xml
                body: /.+/
              mml:
                headers:
                  content-type: application/mathml+xml
                  x-mathoid-style: /.+/
                body: /.+/
        - title: mass-energy equivalence (svg)
          request:
            params:
              format: svg
            body:
              q: E=mc^2
          response:
            status: 200
            headers:
              content-type: /image\/svg/
            body: /^\<svg[\s\S]+svg\>$/
        - title: mass-energy equivalence (mml)
          request:
            params:
              format: mml
            body:
              q: E=mc^2
          response:
            status: 200
            headers:
              content-type: /application\/mathml\+xml/
            body: /^\<math[\s\S]+math\>$/
        - title: mass-energy equivalence (texvcinfo)
          request:
            params:
              format: texvcinfo
            body:
              q: E = m c^2
          response:
            status: 200
            headers:
              content-type: application/json
            body:
              success: true
              checked: /E=mc/
              identifiers:
                - E
                - m
                - c
        - title: Invalid command (texvcinfo)
          request:
            params:
              format: texvcinfo
            body:
              q: a + \invalid = b
          response:
            status: 400
            headers:
              content-type: application/json
            body:
              success: false
              detail:
                error:
                  found: /invalid/
                  location:
                    start:
                      column: 5
  /zlib/{outformat}/{type}/{q}:
    get:
      tags:
        - zLib
      description: Converts a formula encoded in the URI to TeX to SVG, PNG or MathML
        depending on the parameter format. The special format 'texvcinfo' returns
        information about the input without to render anything.
      parameters:
        - name: outformat
          in: path
          description: output type
          required: true
          schema:
            type: string
            enum:
              - texvcinfo
              - speech
              - mml
              - svg
              - png
              - json
              - complete
        - name: type
          in: path
          description: input type
          required: true
          schema:
            type: string
            enum:
              - tex
              - inline-tex
              - mml
              - ascii
        - name: q
          in: path
          description: compressed input to be converted
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
      # TODO: remove and uncomment the below example
      # once T215220 has been resolved
      x-monitor: false
#      x-amples:
#        - title: Get identifiers from compressed mass-energy equivalence formula
#          request:
#            params:
#              outformat: texvcinfo
#              type: tex
#              q: eJxztc1NjjMCAAagAeM=
#          response:
#            status: 200
#            headers:
#              content-type: application/json
#            body:
#              success: true
#              checked: /E=mc/
#              identifiers:
#                - E
#                - m
#                - c
components: {}