Github Actions

1

Create Theneo Documentation

Begin by creating a documentation project within Theneo to house your API details.

2

Set Up GitHub Workflow

Set Up GitHub Workflow

Configure a workflow in your GitHub repository that will interact with Theneo:

• Create a Workflow File: Add a file named Theneo.yml to the .github/workflows/ directory in your GitHub repository. This file will define the actions to be taken.

Example Theneo.yml Workflow:

 
name: Update Documentation
on:
  pull_request:
    branches:
      - main
jobs:
  update-doc:
    name: Update Theneo Documentation
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
      - name: Update Documentation on Theneo
        uses: Theneo-Inc/api-documentation@1.8.0
        with:
          FILE_PATH: doc/api.yml
          PROJECT_SLUG: <project_slug>
          VERSION_SLUG: <version_slug>
          WORKSPACE_SLUG: <workspace_slug>
          SECRET: ${{secrets.SECRET}}
          AUTO_PUBLISH: true
          IMPORT_OPTION: merge
          PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new
          SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old
          INCLUDE_GITHUB_METADATA: true

3

Locating Your Theneo Project Slug

To configure GitHub Actions, you'll need your Theneo project slug:

• Go to your project dashboard in Theneo.
• Open the desired project.
• The project slug is part of the URL: https://app.theneo.io/<workspace-name>/<project-slug>/[version-slug].
• For example, if the URL is https://app.theneo.io/theneo/github-demo, your project slug is github-demo.

Use this project slug for the PROJECT_SLUG variable in your GitHub workflow.

4

Inputs

Define the following inputs in your workflow file to configure the GitHub Action:

• FILE_PATH: The path to your API documentation file within the repository.
• PROJECT_SLUG: Your project's unique identifier in Theneo, accessible under project settings.
• VERSION_SLUG: Project version slug to import documentation under a specific version, otherwise default version will be used.
• WORKSPACE_SLUG: Project workspace slug to import documentation under specific workspace.
• SECRET: Your Theneo API token for authentication, which can be found in your Theneo profile.
• IMPORT_OPTION: Determines how to handle the imported documentation. Options include overwrite, merge, and endpoints.
• AUTO_PUBLISH: If set to true, Theneo will automatically publish the changes. If false, you can review changes in the editor before manual publication.
• INCLUDE_GITHUB_METADATA: Includes metadata like the GitHub actor in the documentation, visible only in Theneo's editor.
• SECTION_DESCRIPTION_MERGE_STRATEGY : Merging strategy for section descriptions to keep old descriptions from theneo editor if needed, valid values are keep_new or keep_old.
• PARAMETER_DESCRIPTION_MERGE_STRATEGY: Merging strategy for parameter descriptions to keep old descriptions from theneo editor if needed, valid values are keep_new or keep_old.

5

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.

6

Auto-Publish Option

Control the publication of your documentation:

• true: Automatically updates the published documentation with the latest changes.
• false: Allows for a review in Theneo's editor before you decide to publish.