Product Updates
Code as Docs Integration: SDKs embedded in your API reference
Sagar Batchu
April 12, 2024 - 2 min read
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 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 . 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.
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:
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:
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.