Code as Docs: The only docs that fully integrate with your SDKs
December 20, 2023
Your users are code-native. Your docs should be too. Today, we're releasing our "code as docs" solution to help companies shift their API references to being code-native.
What's code-native mean? It means fully integrating your SDKs into your documentation so that your documentation reflects how users will actually interact with your API.
And it's not just detailed code snippets. Top to bottom, we've built a solution that reflects what we would want as developers. The feature list includes:
- Code snippets that are compilable and feature the latest version of your SDKs.
- Request & response objects presented in terms of your SDK's type system.
- Generated sections for Authentication, pagination, error handling, and more.
- Easily customisable theming.
- Deep linking & single page scroll so that you can navigate and share any level of your API reference.
- Built on best-in-class open source tools like MDX, Next.js, and CodeHike.
To get started, all you need is an OpenAPI spec. Simply install the speakeasy CLI, and start generating:
brew install speakeasy-api/homebrew-tap/speakeasy
speakeasy generate sdk -s openapi.yaml --output ./sdk -l typescript
Providing users with a generic
fetch call doesn't help them build a live integration with your API. Production integration involves a lot more than just making an HTTP request. Authentication, error handling, pagination parsing, request retries, all need to be considered. SDKs abstract a lot of these concerns for users, which means it's possible to provide a code snippet that is both concise and useful to your users.
All the code snippets in your Speakeasy-generated docs feature the latest version of your SDKs. That means that your users can copy and paste code directly into their IDE and start using your API at scale:
One of the advantages of an SDK is type safety, the developers integrating the API into their application can better understand how the API is intended to be used — and massively reduce the number of incorrect requests being made to your API. Type safety will help developers debug in their IDE as they write the application code, and spare them the frustration of having to comb through the constructed data object to see where/ mistakes occurred.
The more that you can include in your type definition, the more feedback developers will have when they are building with your SDK.
Speakeasy docsites are easily customizable. You can change the colors, fonts, and logos to match your brand. Theme options are intended to be lightweight and easy to use, so you can get your docs up and running quickly. Plus, the docs are built on top of Next.js, so you can easily add your own custom components.
When it comes to docs, it’s small touches that separate the best from the rest. Small usability features can elevate the experience to be a memorable one. Consider the following:
Single page scroll - the ability to scroll through the entire API documentation on a single page. This makes it easy to quickly navigate the documentation and find the endpoint that you are looking for.
Deep linking - the ability to link to directly link any subfield of the documentation. This makes collaboration using documentation 10x easier. For a real live example, see how in the Stripe docs you are able to follow this link to the exact field (opens in a new tab) of an input object to a specific endpoint.
We've built our docs solution on top of the best open source tools available. We use MDX2.0 to combine markdown content with custom React components. We use Next.js and the Nexla theme to create a fast, SEO-friendly, and customizable docs site. Finally, we use CodeHike to create beautiful interactive code snippets featuring your SDKs.
They're the same building blocks that we use to build our own docs, and we're excited to share them with you.