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.
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.
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.
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 backward compatibility support for the old URLs was by 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.
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 URLs, making it easy to call mock servers from outside Stoplight.
- External Links in TOC
- Internal Models don’t hide in TOC
- Multiple Examples of 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.
