A little while ago we announced Stoplight Platform to the world, a revolutionary ecosystem that lets you handle API Design, Documentation, and API Mocking. Unlike other tooling, all this functionality, and the API descriptions and documentation can live in your existing version control system, along with the source code. The new approach handles all this whilst keeping things easy enough for your whole team to use, not just the techie folks.
Let’s have a look at some of those Platform features, and talk about the new Studio Desktop v2.0 release that goes with it!
Stoplight Platform
For those of you new to Platform, it’s what we call the rest of the API design and discovery ecosystem, which is free to use.
Workspaces
Workspaces are a handy way to group API projects across your organization, to promote visibility, and reuse of artifacts. We recommend making a single workspace for your organization and using roles and permissions to effectively manage your workflows.
Read more about workspaces.
Automatic Publishing
Stoplight Platform takes the burden of publishing off of your team. In the past, to update your docs, somebody would have needed to pull changes in Studio Desktop or Studio Web, and manually click a publish button. Alternatively, folks would need to set up continuous integration and/or run a command-line script in order to publish, which is not an easy task for everyone to figure out.
Now, there’s no more Publish button to click, because we’ve got a far easier default approach: Webhooks! If you’re using GitHub, GitLab, or BitBucket, Stoplight will automatically set up Webhooks when you connect your Git repo. These webhooks are events that are triggered whenever new changes are pushed to the repo, and when Stoplight Platform notices these events it’ll automatically update your documentation, Explorer, and mock servers. It even works with multiple branches!
If Webhooks are not an option for any reason, then you can still use the command-line approach, so everyone should be covered one way or another.
Learn how to get robots doing your work, with automatic publishing.
Multiple Branch Support
One of the main goals for Stoplight is not to impose workflows on your organization, and for those using Git we want to support whatever branching model is in use.
Maybe a repository follows Git Flow with master, develop and feature/ branches. Maybe another project has versions spread across multiple version branches, like v3 and v4. Publishing can be enabled for multiple branches, so that whatever workflow you use, multiple branches can have published documentation.
Branches may also be given Display Names to make them more clear to those viewing the documentation, maybe a main branch could be nicknamed “Stable” and develop could be nicknamed “Development”.
Read more about branch management.
Hierarchical Explorer
A powerful full-text search tool for exploring all of the API design assets in your Workspace. The new hierarchical view allows you to quickly traverse the contents of your API projects.
Check out some background on Explorer.
Automatic Hosted Mock Servers
Stoplight provides automatic hosted mock servers for all of your APIs. The mock server will validate all requests and will respond with a dynamically generated response or a specific example.
Theming and Branding
Pick one of the preset themes or provide your own colors to fully customize your workspace’s branding!
Expanded Git Integrations
Stoplight already supports GitHub, GitLab, Bitbucket Cloud, Bitbucket Server, and Gitea. Now we’ve added Team Foundation Server 2018 (v4.1), which has since been renamed to Azure DevOps Server.
Studio Desktop v2.0
For those of you new to Studio Desktop, it’s a standalone application for Windows, macOS, and Linux, which allows you to edit and manage OpenAPI, JSON Schema, AsyncAPI, and Markdown documents locally. Studio Desktop works with files on your computer, has built-in Git functionality, runs local mocking servers for you, and it’s totally free. You can use it with any Git repository or local directory you want, whether it has anything to do with Stoplight or not.
To download the latest version of Studio Desktop, visit the download page here. Studio Web is included in the latest release of Stoplight Platform.
Automatic Publishing
With Publishing now handled in Stoplight Platform, there’s no need for the Publish button anymore, so we’ve gone ahead and chucked that out to clear up the UI for you.
The new docs are published to a new and improved URL for Stoplight.io users, so take a look at how publishing works in Studio v1 & v2.
Git Authentication
In v1, all Git requests were authenticated through Stoplight which required you to login to your Stoplight account. Now you authenticate directly with your project’s VCS provider, including on-premise ones, by providing Studio with a personal access token for your VCS account. This means you can use Studio without needing to login to a Stoplight account, so we’ve removed the login button.
Performance improvements
Performance has seen a whole bunch of improvements in v2, with two areas getting the most attention:
- Project load time
- Git operations, such as Clone, and Commit & Push
Various other efforts have been made to speed up linting, and we now internally work with “bundled” OpenAPI instead of “dereferenced” OpenAPI, which means we can handle much larger files before things start to slow down.
Linter Documentation
Warnings and Errors in the Problems panel (linter messages from Spectral) used to exist in a bit of a vacuum. They’d show up, with one line saying what the problem is, and hopefully people would know what that meant. If you didn’t know what it meant, it was hard to find out more information. We had documentation for core rulesets, but how do people know to look there?
To make this far more obvious, we’ve added links to the ruleset documentation for each linter message. Each rule in the core rulesets will have a bigger explanation in the documentation, covering not just what is wrong, but why it’s a problem, and what it should look like instead.
We recommend folks do this for custom rulesets too, so that everyone understand what they should be doing, instead of just being told they didn’t do something right.
Want to keep an eye on what features we’re considering, what’s currently being developed, and what’s been recently released? Check out our public roadmap where you can submit your ideas, and vote on what we should build next!
