Bitbucket

Bitbucket’s collaborative environment is ideal for teams to manage their codebase. Integrating Bitbucket with Theneo ensures your API documentation stays in sync with your repository changes. Here’s how to set up Bitbucket integration:

Usage

Step 1: Create Theneo Documentation

Initiate your API documentation by creating a project on the Theneo platform.

Prerequisites for Bitbucket Integration

• An established API documentation project on Theneo.
• A generated API key from your account → https://app.theneo.io/account-settings/toolsandintegrations
• Your API documentation file located within your Bitbucket repository.

After setting up the Bitbucket pipeline with the appropriate Theneo variables, your API documentation will automatically reflect changes pushed to your repository. This seamless integration facilitates an up-to-date and accurate representation of your API for developers and stakeholders.

Step 2: Configure Bitbucket Pipeline

Incorporate Theneo's automation into your Bitbucket repository:

• Add a Pipeline: Integrate Theneo's pipeline into your bitbucket-pipelines.yml file to update your Theneo documentation with each repository update.
• Configure the Pipeline: Use the snippet below in your bitbucket-pipelines.yml file to set up the pipeline.

For Importing a single API Spec

 
# bitbucket-pipelines.yml
image: node:22

pipelines:
  default:
    - step:
        name: Import OpenAPI spec to Theneo
        caches:
          - node
        script:
          # Install CLI + login
          - npm install -g @theneo/cli@latest
          - echo "Logging in to Theneo..."
          - theneo login --token "THENEO_API_KEY"

          # Import the spec file
          - |
            theneo project import \
              --project "THENEO_PROJECT_KEY" \
              --workspace "$THENEO_WORKSPACE_SLUG" \
              --publish \
              --file "API_DOCUMENT_PATH" \
              --import-type merge

Variables for Bitbucket Pipeline:

• API_DOCUMENT_PATH: The path to your API spec within your repository. e.g docs
• THENEO_PROJECT_KEY: The unique slug of your Theneo project. Find this in your Theneo project URL: https://app.theneo.io/[workspace-name]/[project-slug]. For example, if your Theneo project URL is https://app.theneo.io/theneo/bitbucket-demo, the bitbucket-demo is your project slug.
• THENEO_API_KEY: Your Theneo API key, which you can generate from the Theneo website.

Sample script

# bitbucket-pipelines.yml
image: node:22

pipelines:
  default:
    - step:
        name: Import OpenAPI spec to Theneo
        caches:
          - node
        script:
          # Install CLI + login
          - npm install -g @theneo/cli@latest
          - echo "Logging in to Theneo..."
          - theneo login --token "8dd818-f628-40fd-9ff2-b84f7d42da6d"

          # Import the spec file
          - |
            theneo project import \
              --project "demo" \
              --workspace "demo" \
              --publish \
              --file "docs/petstore.yaml" \
              --import-type merge 

In here, this is my sample token --token "8dd81-f628-40fd-9ff2-b84f7d42da6d", testdoc is the project slug --project "testdoc" , and my api spec is located here docs/petstore.yaml

Import Options

Choose how Theneo handles incoming changes:

• overwrite: Replaces the current documentation with the new spec entirely.
• merge: Attempts to merge changes; this is experimental and may append changes in some cases.
• endpoints: Adds new spec endpoints into a dedicated section for manual arrangement.

For Importing an entire folder (markdowns + API)

If you would like to import exported markdown content + API configuration, then you can use the following script

 
# bitbucket-pipelines.yml
image: node:22

pipelines:
  default:
    - step:
        name: Push OpenAPI to Theneo
        caches:
          - node
        script:
          - npm install -g @theneo/cli@latest
          - echo "Logging in to Theneo..."
          - theneo login --token "THENEO_API_KEY"
          - echo "Listing Theneo projects..."
          - theneo project list
          - echo "Importing OpenAPI spec to Theneo..."
          - echo "Updating a Project in Theneo..."
          - theneo import --project "THENEO_PROJECT_KEY" --workspace "Workspace_name" --dir path_to_yourfolder