Mintlify API docs integration

This guide will walk you through the steps to integrate liblab’s enhanced API specification with Mintlify. With this integration, you can publish OpenAPI documentation enhanced with SDK code samples generated by liblab on Mintlify, providing developers with dynamic, up-to-date API documentation.

liblab automates the process of generating SDKs and enhancing your OpenAPI spec with SDK code examples in multiple programming languages, simplifying the creation of comprehensive API documentation.

Prerequisites

Before you start, ensure you have:

• A liblab account.
• The liblab CLI installed.
• A Mintlify account.
• A GitHub organization to host your project.
• A GitHub token with the necessary permissions (read/write access to repositories).

1. Create a Mintlify Project

To begin, you’ll need to create a Mintlify project. Follow these steps to create one:

1. Sign up to Mintlify.
2. Verify your account through the confirmation link sent to your email.
3. Once verified, you’ll be directed to the onboarding process. Mintlify offers two options:     - GitHub Integration: Connect your GitHub account and provide access to your organization's public repositories.    - Mintlify Template (used in this tutorial): Create a new public documentation repository using the Mintlify starter template. You'll need to specify your GitHub Organization and Repository Name.
4. Click Go to dashboard to complete the onboarding process.

In the Mintlify dashboard, you'll have access to:

• Your documentation link.
• The repository and branch used for deployment.
• Other Mintlify settings.

To view your documentation:

1. Click Visit docs.
2. Once on the documentation portal, click API Reference.

You will now see the default Mintlify API documentation with three sample endpoints. In the following steps, we’ll update this to create documentation for your API.

2. Install the GitHub App

The integration of liblab and Mintlify involves pushing and tracking changes from the repository created in Step 1. The repository serves two purposes:

• Mintlify gets the repository's content every time the main branch is updated to update the documentation.
• liblab pushes the OpenAPI file to the repository after creating new SDKs and the enhanced OpenAPI spec.

You'll need to install the Mintlify GitHub App in the repository to enable continuous updates and track changes. To install the GitHub App, follow these steps:

1. Open the Mintlify dashboard.
2. Go to Settings > GitHub App.
3. Click Install GitHub App.
4. You'll be redirected to GitHub's App installation page. Select the repository you created in Step 1 and click Install & Authorize.

Once installation is complete, you'll be redirected back to the Mintlify dashboard, and a documentation update will be triggered. You should also see the Installed label under Settings > GitHub App, indicating the successful App installation.

3. Update the Documentation

Next, you'll update the documentation by replacing the default content with your OpenAPI spec.

3.1 Clone the GitHub Repository

Clone the repository created in Step 1 to your local machine. The initial repository structure will look like this:

Repository structure

liblab-mintlify/
├── api-reference/
│   ├── endpoint/
│   │   ├── create.mdx
│   │   ├── delete.mdx
│   │   └── get.mdx
│   ├── introduction.mdx
│   └── openapi.json
├── development.mdx
├── essentials/
├── favicon.svg
├── images/
├── introduction.mdx
├── logo/
├── mint.json
├── quickstart.mdx
├── README.md
└── snippets/

The Mintlify starter template includes example files that you can use to structure your documentation. For this tutorial, you will focus on the contents of the api-reference/ directory.

3.2 Generate API Reference Pages

Mintlify generates documentation pages from an OpenAPI specification. For example, the create.mdx, delete.mdx, and get.mdx files in the api-reference/endpoint/ directory were generated based on the existing api-reference/openapi.json file.

To update the documentation with your OpenAPI spec, follow these steps:

1. Remove all the files in the api-reference/ directory, keeping only the openapi.json.
2. Replace the openapi.json file content with your own API spec. In this tutorial, we'll use the PetStore API.
3. After updating the openapi.json file, run the following command to generate MDX files for your OpenAPI endpoints. If you’re using a public hosted OpenAPI document, you can supply the URL instead of a file path. The following Tutorial example command uses the openapi.json file to generate the endpoint files created under the /api-reference directory.

General command

  npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <destiny-path-to-save-MDX-files>

Tutorial example

  npx @mintlify/scraping@latest openapi-file ./api-reference/openapi.json -o ./api-reference

Autogenerate files

Access the Mintlify documentation to learn more about the file generation process.

4. The generated MDX files will appear in the specified directory. After generating the endpoint pages using the PetStore API, your directory structure should look like this:

Repository structure

  liblab-mintlify/
  ├── api-reference/
  │   ├── introduction.mdx
  │   ├── openapi.json
  │   ├── pet/
  │   │   ├── add-a-new-pet-to-the-store.mdx
  │   │   ├── deletes-a-pet.mdx
  │   │   ├── find-pet-by-id.mdx
  │   │   ├── finds-pets-by-status.mdx
  │   │   ├── finds-pets-by-tags.mdx
  │   │   ├── update-an-existing-pet.mdx
  │   │   ├── updates-a-pet-in-the-store-with-form-data.mdx
  │   │   └── uploads-an-image.mdx
  │   ├── store/
  │   │   ├── delete-purchase-order-by-id.mdx
  │   │   ├── find-purchase-order-by-id.mdx
  │   │   ├── place-an-order-for-a-pet.mdx
  │   │   └── returns-pet-inventories-by-status.mdx
  │   └── user/
  │       ├── create-user.mdx
  │       ├── creates-list-of-users-with-given-input-array.mdx
  │       ├── delete-user.mdx
  │       ├── get-user-by-user-name.mdx
  │       ├── logs-out-current-logged-in-user-session.mdx
  │       ├── logs-user-into-the-system.mdx
  │       └── update-user.mdx
  ├── development.mdx
  ├── essentials/
  ├── favicon.svg
  ├── images/
  ├── introduction.mdx
  ├── logo/
  ├── mint.json
  ├── pet/
  ├── quickstart.mdx
  ├── snippets/
  └── store/

5. After running the command, Mintlify will generate a navigation object that appears in your terminal. Add this object to the mint.json file under the navigation attribute. Thus, the new documentation page will be visible on your documentation portal.

Mintlify Navigation settings

Access the Mintlify navigation documentation to learn how to configure the sidebar and make page visible for your documentation users.

6. Preview the documentation by running the following command in your terminal:

mintlify dev

7. Save all files and push the changes to GitHub.

Mintlify will automatically detect changes to the branch you defined in the dashboard. For this tutorial, Mintlify is using the main branch. Once the update is complete, your API endpoints will be available in the documentation.

Access the API Reference tab in your documentation to see all the available endpoints.

4. Create a GitHub Token

After setting your Mintlify project, generate a GitHub token to enable liblab to create pull requests (PR) in your documentation repository. This token ensures your repository's OpenAPI spec is automatically updated whenever you use liblab to create SDKs and the enhanced OpenAPI spec.

Follow these steps to create the token:

1. Navigate to your GitHub profile and click Settings.
2. In the sidebar, click Developer Settings.
3. At the Developer Settings page, select Personal access tokens > Fine-grained tokens.
4. Click Generate new token.
5. Name the token LIBLAB_GITHUB_TOKEN and set its expiration. For production documentation, choose No expiration.
6. For Resource owner, select the organization that owns the repository created in Step 1.
7. Select Only select repositories under Repository Access and choose the repository you created in Step 1.
8. Set the following repository permissions:     - Commit Statuses: Read/Write.     - Contents: Read/Write.     - Metadata: Read.     - Pull Requests: Read/Write.     - Workflows: Read/Write.

9. Click Generate token.

CI/CD documentation

Access the Pull request creation documentation page for further information and detailed guidance on creating the token.

Once created, copy the LIBLAB_GITHUB_TOKEN and save it in a secure location for use in the upcoming steps. For more details on how the LIBLAB_GITHUB_TOKEN will be used to create PRs, access the liblab documentation.

5. Configure the liblab Project

Now, you’ll integrate liblab to automatically update the OpenAPI specification in the repository created in Step 1.

liblab generates SDKs based on your OpenAPI spec and enhances the spec by adding elements like code snippets and SDK examples. These enhancements improve the developer experience by providing clear documentation. Integrating liblab makes your API documentation more dynamic, maintaining accuracy and consistency across every update with minimal manual effort.

Enhance the OpenAPI spec

Access the API and SDK documentation overview to learn more about how liblab enhances the OpenAPI spec.

5.1 Create the liblab Project

In a new repository, initialize a liblab project with the following command:

liblab init

A new liblab.config.json file will be created in the directory. Update it to use the same OpenAPI spec as in Step 3.2. For this tutorial, we're using the PetStore API:

{
  "sdkName": "petstore",
  "apiName": "petstore",
  "specFilePath": "https://petstore.swagger.io/v2/swagger.json"
}

By default, when you initialize a liblab project, it's set to generate SDKs for the following programming languages:

• C#
• Go
• Python
• TypeScript

You can customize the list of programming languages as needed. However, remember that the languages you specify in your liblab configuration file will be used to create the enhanced OpenAPI spec. This enhanced spec will include your OpenAPI definition and SDK code snippets for each selected language. Mintlify will later use the enhanced OpenAPI spec to generate a new version of your API documentation.

5.2 Configure the GitHub Organization

To ensure liblab pushes changes to the correct repository after enhancing the API, you need to update the liblab.config.json file with the organization or username that owns the repository created in Step 1. Add the following to your liblab.config.json file:

liblab.config.json

{
  "publishing": {
    "githubOrg": "<your-organization-name>"
  }
}

note

If you own the repository from Step 1, use your GitHub username as the githubOrg.

5.3 Configure Integration Setting

In addition to specifying the organization, you must configure the integration to generate the API documentation. This information should be placed within the integrations.enhancedApiSpec object. Update the liblab.config.json file with the following information:

• provider: The API documentation provider, which for this tutorial is mintlify.
• githubRepoName: The GitHub repository hosting the API documentation project. Use the repository created in Step 1.
• targetBranch: The base branch from which liblab will create a new branch. This new branch will be used to open the pull request. By default, the main branch is used as the base.

The following snippet provides the code to add to your liblab.config.json file. Note that the path to the OpenAPI spec isn't provided.

liblab.config.json

{
  "integrations": {
    "enhancedApiSpec": {
      "provider": "mintlify",
      "githubRepoName": "<your-repo-name>",
      "targetBranch": "main",
    }
  }
}

API documentation providers

Access the API documentation providers page for further information.

5.4 Set up the GitHub Tokens

To enable the liblab to make changes to the repository created in Step 1, you need to set the GitHub token as an environment variable. Follow these steps:

1. Open a terminal and navigate to the repository's root directory you created for the liblab project in Step 5.1.
2. Run the following command to export the token, replacing <your_token> with the LIBLAB_GITHUB_TOKEN generated in Step 4:

  export LIBLAB_GITHUB_TOKEN=<your_token>

Once the token is exported, liblab will have the required permissions to push updates to the repository.

6. Enhance the OpenAPI

After configuring the liblab project, you can build it to generate the SDKs and the enhanced OpenAPI spec. To build the project, use the following command:

liblab build -y

liblab will create a PR in your repository. A new branch called liblab-api-documentation-update-<Date> will be created for the pull request. This branch is based on the target branch you specified or on main if no branch was specified.

Once your enhanced API Spec has successfully been created and added to your repository, your terminal will display a message like the one below:

-MINTLIFY API DOCUMENTATION INTEGRATION --------------------------------------
Creating a new branch for API documentation
Owner: <your-organization-name>
Repository: <your-repo-name>
Branch Name: liblab-api-documentation-update-1730114110938
Committing files to branch
git#push: Authenticating for: https://github.com/<your-organization-name>/<your-repo-name>.git
Successfully created PR for Enhanced API spec: https://github.com/<your-organization-name>/<your-repo-name>/pull/<pull-request-number>

You can access the PR and check the modified files using the link. In addition, you can merge the changes made by liblab into the main branch. The following image presents an example of the commit with the OpenAPI spec enhancements performed by liblab.

7. Access the New Documentation

After merging the PR, Mintlify will identify the new content on the main branch and trigger the deployment of the new documentation.

Access your documentation portal to view the results of the OpenAPI spec enhancements made by liblab. Below is an example of the updated documentation using the enhanced PetStore API spec, which now includes SDK code samples for the programming languages generated by liblab.

Conclusion

Integrating liblab with Mintlify provides a powerful, automated solution for keeping your API documentation up-to-date, complete with SDK code samples in multiple programming languages. This integration simplifies updates and enhances the developer experience with accurate, easily accessible documentation, ensuring your API documentation remains synchronized with every new release.