Product release: A Comprehensive Developer Experience for APIs

Job Rietbergen

Apr 13, 2023

We’ve shipped big improvements to help you create an even better experience for your APIs.

This latest Alphadoc release includes new features and functionalities that help create a compelling DX on top of your APIs and onboard developers seamlessly onto it.

It’s a big revamp under the hood of the Alphadoc platform.

Background: The Importance of a Good OpenAPI Specification

The OpenAPI Specification is a widely used standard for HTTP APIs. It allows both humans and computers to easily understand these APIs. Alphadoc has built its initial tooling around it, given its popularity in the market. However, despite its popularity, it’s hard to write correctly defined API spec files. This release aims to help anyone automate and maintain the developer onboarding by making sure the OpenAPI spec is flawless and can be used as the source of truth.

We’ve gone deep down the OpenAPI Specification rabbit hole, so you don’t have to.

Refactored Alphadoc’s Own APIs

We’ve done a complete overhaul of our own APIs that power the UI inside our platform. These APIs are available upon request for anyone to use and embed Alphadoc deeper into the workflow.

Auto-updating API Components Upon New OpenAPI Spec File Uploads

Whenever you upload a new spec file, we automatically update all connected API endpoints and parameters referenced across your docs and tutorials. This feature is a significant improvement to streamline your documentation process and ensure the docs stay in sync.

Built Tooling that Converts a Postman Collection into an OpenAPI Spec File

We recommend anyone who’s building APIs starts with a good OpenAPI Specification and convert the spec to a Postman Collection afterward if needed — and not the other way around. Therefore we wrote scripts to help easily convert a Postman Collection into an OpenAPI spec, so it can be used as the single source of truth for the docs.

Custom Subdomain for Developer Portal

We added support for custom subdomains. All you have to do is tell us the desired domain and make a simple one-off change to your DNS settings. This feature ensures the developer portal is fully aligned with your brand and creates a more seamless developer experience.

Fixes & other improvements

Improved stability and UI for API components
Added support for .yml OpenAPI spec files
Added support for OpenAPI files without tags
Added support for tables, separators, and highlighting
Added Intercom for support and improved the overall onboarding experience for first-time users
Fixed bug with inline code styling
Fixed bug with hiding and showing of docs and tutorials
Fixed bug in sign-in screen for first-time
Fixed image widths when editing docs and tutorials

Sum up

The latest Alphadoc release brings a new set of developer experience features for your APIs. With the implementation of the OpenAPI validator, refactored APIs, redesigned visual API components, auto-updating API components, and tooling that converts Postman Collection into OpenAPI, this release lays much of the groundwork for automatically creating and maintaining your docs and tutorials.

Additionally, the custom subdomain is much requested by our users to adapt the platform to their brand.

Getting Started

To start building your docs & DX with Alphadoc, please fill out the sign-up form or visit our website at alphadoc.io. We’ll review your request for beta access within 1 business day. Once granted access, you can upload your OpenAPI spec and easily generate your docs & tutorials on the platform.