Create Flawless API Documentation with Stoplight Hubs
Create Flawless API Documentation with Hubs
At Stoplight, our goal is to build, maintain, and grow a holistic platform that encompasses your entire API strategy. We strive to make Stoplight your home base for all things API.
With that in mind, we’re excited to announce the launch of Hubs. Hubs is the newest module in the Stoplight arsenal, and it addresses a key area of focus for API users: documentation.
We know from our own previous experience (and that of our users) that creating and maintaining API documentation is an arduous process. API docs often exist independently from specs and testing, are disconnected from those functions, and have no consistent format.
Documentation doesn’t get updated regularly and becomes out-of-date, and the “real” guidelines might live in someone’s head. This can cause errors in usage, misinterpreted (or missing) data, and a whole host of other issues.
We want to change that narrative by coupling your API documentation with your API Spec. Our trimmed-down interface provides the structure you need to create meticulous documentation AND the freedom to use your own style. With Hubs, it’s easy to create docs, maintain them, and consume them.
Here’s a 10,000 foot view of what you can accomplish using Hubs:
Build Structured API Documentation
Generate a distinct Hub for any form of API documentation. Within that Hub, break down your documentation into pages and nested subpages. Choose from a laundry list of block types to create content, depending on how simple (or complex) your documentation is. Block types include text blocks, code snippets, images, callouts, and more.
Quickly Assemble API Docs
Yes, Virginia, you can build complex API documentation using Hubs — and it won’t take you countless hours. We’ve done a lot of the upfront work to make it easier on your end. Block types like JSON schema and HTTPS request maker allow you to easily drop code or URLs into a preformatted block — no coding required (unless you want to).
URL routing is built into the page/subpage creation process, so all URLs reflect the location in your docs hierarchy (with no manual input required from you). And if you happen to place a block in the wrong spot, you can just drag and drop it to the correct location — there’s no need to delete it and start all over.
Easily Toggle between Read, Design, and Code Mode
API documentation tools generally have both editor and preview modes, but they don’t always play well together. In many cases you have to perform multiple operations to preview your documentation. Sometimes you save docs and the preview looks (a) nothing like what’s in the editor or (b) totally different from what users are seeing.
Hubs inline editing tools allows for a seamless experience between editor and preview. With one click, you’ve switched between modes. All changes are auto-saved, so there’s no “oof!” moments if you forget to save changes.
Offer API Docs in a Consumable Format
Gone are the days of boring, bland API docs — those long blocks of text broken up by a few headers. The Hubs toolset allows you to format API documentation with many of the same functions users have come to expect on the broader web.
Pepper docs with images and videos to break them up and illustrate examples, and use callout blocks to draw attention to important points. Employ tab blocks when you have a lot of related text but want to keep the page length short. All these functions will help make documentation easier to read, and more likely to be consumed.
Connect API Docs to your Spec in Stoplight
If your API lives in Stoplight alongside your documentation, now’s the time to connect the two. Use OpenAPI to directly link your Spec to your Documentation in Hubs. You can find the OpenAPI URL of your spec in the Modeling module of Stoplight. By adding it to the API docs, you can pull all the inputs from the spec into your docs. That way, if the spec changes, your API docs automatically update.
Connect API Docs to your External API Platform
Even if you use another platform to host your API, you can still plug your live spec into API documentation in Stoplight. Just grab your external OpenAPI URL and add it as an external data source for your docs. Now your API docs are pulling the most updated version of your live spec, even though it’s hosted outside the Stoplight platform.
Hubs is Live, but we’ve still got work to do
We’re thrilled to be able to share Hubs with our existing user base. We’ve already received lots of valuable feedback (shout out to our Beta users) to help us make the best product for you, our user. As you go through and create your API docs, let us know what works for you — and what doesn’t. Drop us a line at support@stoplight.io, or use the in-app chat to share your thoughts.
