bump.openapi.v3.yml

openapi: "3.0.2"
info:
  title: Bump Api
  description: >
    This is the official Bump API documentation. Obviously created with Bump.
  version: "1.0"
servers:
  - url: https://bump.sh/api/v1
x-topics:
  - title: Authentication
    content: |
      # Api token authentication

      Use the token from your documentation settings as the username of the basic auth, with no password.

      Example: `curl https://bump.sh/api/v1/docs/1/versions -u DOC_TOKEN:`

      Note that adding a colon after your token prevents cURL from asking for a password.
paths:
  /versions:
    post:
      summary: Create a new version
      description: >
        Deploy a new version for a given documentation, which will become the current version.
      requestBody:
        $ref: "#/components/requestBodies/Version"
      responses:
        "200":
          description: "Success"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /validations:
    post:
      summary: Validate a documentation definition
      description: >
        Validate a definition against its schema (OpenAPI or AsyncAPI) and return errors without
        creating a new version. This is useful in a CI process, to validate that a changed
        definition file is valid and won't fail when being deployed on Bump.
      requestBody:
        $ref: "#/components/requestBodies/Version"
      responses:
        "200":
          description: "Success"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /previews:
    post:
      summary: Create a preview
      description: >
        Create a preview for a given documentation file. The preview will have a unique
        temporary URL, and will be active for 30 minutes.
      requestBody:
        $ref: "#/components/requestBodies/Preview"
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Preview"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /ping:
    get:
      summary: Check the API status
      description: Responds a pong if the API is up and running.
      responses:
        "200":
          description: "Success"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Pong"
        default:
          description: API is currently down

components:
  requestBodies:
    Preview:
      description: The version object
      content:
        "application/json":
          schema:
            required:
              - definition
            properties:
              definition:
                type: string
                description: >
                  Serialized definition of the version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file
                  serialized as a string, in YAML or JSON.
                example: |
                  {asyncapi: "2.0", "info": { "title: ... }}
              specification:
                type: string
                description: 'Specification for the definition, as a path: `speficiation_name/specification_version/format`. Example: `openapi/v2/yaml`.'
                enum:
                  - openapi/v2/yaml
                  - openapi/v2/json
                  - openapi/v3/yaml
                  - openapi/v3/json
                example: openapi/v2/yaml
              validation:
                type: string
                description: |
                  Validation strategy:
                  - `basic`: basic validation (default)
                  - `strict`: validate the file against its specification
              references:
                type: array
                description: Import external references used by `definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.
                items:
                  $ref: "#/components/schemas/Reference"
    Version:
      description: The version object
      content:
        "application/json":
          schema:
            required:
              - definition
            properties:
              documentation_id:
                type: string
                description: UUID of the documentation. Required if `documentation_slug` is empty.
              documentation_slug:
                type: string
                description: Slug of the documentation. Required if `documentation_id` is empty.
              hub_id:
                type: string
                description: UUID of the hub if the documentation is part of a hub.
              hub_slug:
                type: string
                description: Slug of the hub if the documentation is part of a hub.
              auto_create_documentation:
                type: boolean
                default: false
                description: Create the documentation if not existing yet. Must be used with a `hub_id` or `hub_slug`, and a `documentation_slug`.
              definition:
                type: string
                description: >
                  Serialized definition of the version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file
                  serialized as a string, in YAML or JSON.
                example: |
                  {openapi: "3.0", "info": { "title: ... }}
              specification:
                type: string
                description: 'Specification for the definition, as a path: `speficiation_name/specification_version/format`. Example: `openapi/v2/yaml`.'
                enum:
                  - openapi/v2/yaml
                  - openapi/v2/json
                  - openapi/v3/yaml
                  - openapi/v3/json
                example: openapi/v2/yaml
              validation:
                type: string
                description: |
                  Validation strategy:
                  - `basic`: basic validation (default)
                  - `strict`: validate the file against its specification
              references:
                type: array
                description: Import external references used by `definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.
                items:
                  $ref: "#/components/schemas/Reference"
  responses:
    "InvalidDefinition":
      description: Definition is not valid.
      content:
        "application/json":
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Reference:
      type: object
      properties:
        location:
          type: string
          description: Location of the external reference as it's called from `definition`, without the relative path (the part after `#/`). Can be an URL of a file system path.
          example: https://example.com/api/models/pet.yml
        content:
          type: string
          description: Content of the external reference, as a string.
    Error:
      properties:
        message:
          type: string
          description: Human readable error message.
          example: Invalid definition file
        errors:
          type: object
          description: Hash of invalid attributes with their error messages.
          example:
            raw_definition:
              - The property '#/paths//docs/{:id}/validations/post' contains additional properties ["yolo"] outside of the schema when none are allowed
    Pong:
      properties:
        pong:
          type: string
          description: Sentence about ping and pong
          example: And that's how ping-pong ball is bumped

    Preview:
      properties:
        id:
          type: string
          description: "Unique id for the preview URL: `https://bump.sh/preview/:id`."
          example: 3ef8f52f-9056-4113-840e-2f7183b90e06
        expires_at:
          type: string
          format: date-time
          description: Preview expiration date and time.
          example: 2010-04-14T17:05:00+01:00