Product Updates

Code as Docs Integration: SDKs embedded in your API reference

Sagar Batchu

April 12, 2024

Production integration with an API involves a lot more than just making an HTTP request. So your docs need to do more than provide users with a generic fetch call.

Today, we’re partnering with Mintlify (opens in a new tab) to release our new “code as docs” integration to help companies shift their API references to being code-native. You can now fully integrate your SDKs into your documentation provider so that building a production integration with your API is as easy as ⌘c, ⌘p.

Building with Mintlify

We spent the last two months in close collaboration developing the SDK Docs solution with the stellar team over at Mintlify (opens in a new tab). Our shared commitment to Developer experience and building OpenAPI-based tooling made the team at Mintlify natural launch partners. We couldn’t be more excited to work together towards our shared vision of making API integrations as easy as possible for developers.

Your users always know best. Even before we officially met Speakeasy, we were familiar with the product because we had tons of shared users and they were describing Speakeasy with the same vocabularly which we use at Mintlify: “developer-centric”, “attention to detail”, “extensible”. Working together has been like an extension of our team.

Han Wang, Co-founder @ Mintlify

How It Works

For every method in your OpenAPI spec, we will generate code snippets that demonstrate use of your SDK to make the corresponding API request. We then add these snippets back into your spec using the x-codeSamples extension.

To enable the new feature, you simply make a one line change to your Speakeasy workflow file:

targets:
  my-target:
    target: typescript
    source: my-source
    codeSamples:
      output: codeSamples.yaml

With your new workflow configured, we will regenerate snippets and create an updated OpenAPI spec.

Point your docs provider at the new spec, and you’re good to go!

Supported documentation

This feature was developed in partnership with Mintlify, but was designed for extensibility. It should be compatible with any documentation vendor that supports the x-codeSamples extension. That includes:

• Mintlify (opens in a new tab)
• Redoc (opens in a new tab)
• Readme (opens in a new tab)
• Stoplight (opens in a new tab)
• Many more

The Future

As we look ahead, the integration of SDKs into documentation platforms like Mintlify is only the beginning. We are working to enhance code snippets to be, not just copiable, but fully executable within a live sandbox environment.

This transformative feature will empower developers to bootstrap production usage directly from the documentation pages.