Stoplight Docs just got a whole lot better, and you don't have to change a
thing to enjoy it. We've refreshed the entire interface, simplified the 'Try It'
console, added support for loads of OpenAPI validations, and even upped our
OpenAPI support to v3.1 - the latest and greatest version of OpenAPI which is
100% compatible with JSON Schema.


Much of Stoplight is built on top of our popular open-source offerings, like
Prism, and Spectral. Now, Stoplight Elements, our new premier open source
API documentation tool is powering the Stoplight Docs experience too. If you
don't want hosted API docs you can use this free tool anywhere else, to turn
any OpenAPI document into something beautiful and useful to your API
customers.


The new Stoplight Docs experience and the latest releases of Elements
have all been made possible by the amazing feedback we received from the
early adopters. Here are a few of the latest changes that both our open-
source community, and Stoplight Platform users, can now enjoy.

Multiple Servers

The "Try It" component will now display all defined servers. This is only
available for OpenAPI v3.0 and v3.1, as OpenAPI v2.0 does not support
multiple servers.

DraggedImage
This can help you point end-users to a staging environment, or if you have
your own sandbox environments you can point them to that instead of using
Stoplight's hosted mock server.

Multiple Auth Types

There are some scenarios where a particular endpoint might have multiple
security schemes of the same type.
 DraggedImage-1
 
When that happens, Elements will now display the security scheme name in
the badge.

Pretty Responses in Try It

HTTP Responses can be all sorts of things. If you've got a cat gif being returned by an API, you can now see it in the response box.

Screen Recording 2021-09-13 at 5.20.30 PM

Performance Improvements

Users of Elements Dev Portal v1.0, and Stoplight Docs running in Preview Mode might have noticed a few performance issues. The way we implemented some backwards compatibility support for the old URLs was adding an extra API call in the background, and we've managed to get rid of that whilst still providing the same support for old and new URLs.

This 2x improvement in loading times brings the latest documentation experience in line with the performance of previous versions, but we're always looking for ways to speed things up further.

Embed All Day

We support embedding a variety of content from popular websites! To use an embed, just write out a link in its own paragraph. Everything from Youtube embeds to gifs, and even audio files work this way!

Currently, Twitter, GitHub Gists, Codepen, Runkit, Replit, YouTube, Vimeo, Figma, Slideshare, SpeakerDeck, and more are supported.

Screen Shot 2021-09-14 at 10.15.31 AM

Other Improvements

  • Servers now have a copy button on hover
  • Try-it can be embedded in Markdown, using the same syntax as the old Request Maker.
  • Updated code samples with mock URL, making it easy to call mock servers from outside Stoplight.
  • External Links in TOC
  • Internal Models don't hide in TOC
  • Multiple Examples for Schemas
  • Fixed PATH requests in Try It Out
  • Fixed clicking on Auth badge to API Auth information

Thanks to all these improvements and bug fixes, we feel confident you'll all love the new documentation experience. Stoplight Platform users will now see the new docs enabled, and all old links should be redirected to help users find the new content.

We believe documentation is a crucial part of the API lifecycle and an important part of the developer experience. Everyone should have access to high-quality, easy-to-manage documentation for their APIs, whether they want to use a hosted SaaS solution, or self-host their own documentation with open-source tools, so we are going to continue to improve both offerings.

If you're a fan of the open-source Elements, please head over to GitHub and leave a GitHub Star. Have additional feedback or questions about the new Stoplight Docs? Email feedback@stoplight.io.

Need help or want to discuss ways to use this tool? Join our Discord community and get help in the #Elements channel.

Peek-a-Boo (1)

Subscribe for the latest in API Design

By submitting this you will be receiving our latest updates on post.

Take a Listen to API Intersection

The podcast on the intersection between API design & digital transformation
Listen

Related Posts