openapi: 3.2.0
info:
  title: Blueprint Parser API
  version: 1A
  summary: API Blueprint parsing service
  description: The API Blueprint parsing service provides parsing of API Blueprint "as a service".
  license:
    name: MIT
    identifier: MIT
  contact:
    name: API Blueprint
    url: https://apiblueprint.org
servers:
- url: https://api.apiblueprint.org
  description: Production parsing service (declared as HOST in the provider's apiary.apib)
tags:
- name: Parser
  description: Parse an API description format into API Elements.
paths:
  /parser:
    post:
      tags:
      - Parser
      operationId: parseApiDescription
      summary: Parse
      description: Parse an API description format. API Blueprint parsing is performed as it is provided by the Drafter reference parser. The output is the Refract data structure conforming to the Parse Result Namespace.
      parameters:
      - name: Accept
        in: header
        required: false
        description: Desired output media type. One of `application/vnd.refract.parse-result+json`, `application/vnd.refract.parse-result+yaml`, optionally qualified with `; version=1.0` or `; version=0.6`.
        schema:
          type: string
          enum:
          - application/vnd.refract.parse-result+json
          - application/vnd.refract.parse-result+yaml
          - application/vnd.refract.parse-result+json; version=1.0
          - application/vnd.refract.parse-result+yaml; version=1.0
          - application/vnd.refract.parse-result+json; version=0.6
          - application/vnd.refract.parse-result+yaml; version=0.6
        example: application/vnd.refract.parse-result+json
      requestBody:
        required: true
        description: The API description document to parse.
        content:
          text/vnd.apiblueprint:
            schema:
              type: string
              description: An API Blueprint document.
          text/vnd.legacyblueprint:
            schema:
              type: string
              description: A legacy API Blueprint document.
          application/swagger+json:
            schema:
              type: string
              description: A Swagger 2.0 document in JSON.
          application/swagger+yaml:
            schema:
              type: string
              description: A Swagger 2.0 document in YAML.
      responses:
        '200':
          description: Parse result in the Refract Parse Result Namespace.
          content:
            application/vnd.refract.parse-result+json:
              schema:
                $ref: '#/components/schemas/ParseResult'
            application/vnd.refract.parse-result+yaml:
              schema:
                type: string
        '406':
          description: None of the requested output media types is supported.
          content:
            application/vnd.error+json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: The supplied input media type is not supported.
          content:
            application/vnd.error+json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Content-Type "undefined" is not supported. Supported MIME types: text/vnd.apiblueprint, text/vnd.legacyblueprint, application/swagger'
        '422':
          description: The document could not be parsed. The parse result carries the annotations describing the errors.
          content:
            application/vnd.refract.parse-result+json:
              schema:
                $ref: '#/components/schemas/ParseResult'
            application/vnd.refract.parse-result+yaml:
              schema:
                type: string
components:
  schemas:
    ParseResult:
      allOf:
      - $ref: '#/components/schemas/ApiElement'
      description: 'A Refract Parse Result element (`element: parseResult`) whose content carries the parsed API category plus any annotations.'
    ApiElement:
      type: object
      description: A Refract / API Elements element. Structure is defined by the API Elements element schema, saved in this repository at json-schema/api-blueprint-api-elements-element-schema.json.
      properties:
        element:
          type: string
        meta:
          type: object
        attributes:
          type: object
        content: {}
      required:
      - element
    Error:
      type: object
      description: The vnd.error media type as used by this API. Carries a single human readable message.
      properties:
        message:
          type: string
      required:
      - message
externalDocs:
  description: API Blueprint API documentation on Apiary
  url: https://apiblueprintapi.docs.apiary.io/