Today we are thrilled to share Stoplight Studio, our new free API designer, built with the modern development workflow in mind.
Previous versions of Stoplight required you to keep your API description documents on our servers, but Stoplight Studio includes first class git support (yes, even in the browser!), which allows you to use your existing version control system. We analyze git repositories to find relevant files, and give you a beautiful visual editor to create your API designs. When ready, you can commit the changes directly to your git repository (GitHub, Bitbucket, GitLab, etc). This makes integration with your own PR workflows and build pipelines easy, and means your API descriptions and docs can now live right alongside your code.
We’ll share a lot more about Stoplight Studio over the coming weeks, but here’s a quick look at what is available today:
Stoplight Studio is completely free for individuals - you don’t even need an account to use it. We want everyone to have access to the best API design tooling, without compromises or vendor lock-in. For four years, that’s been our goal, and we believe Studio is a huge step towards delivering on that promise. Before going further, let’s take a quick walk through Stoplight’s evolution over the years.
When Stoplight was founded, declarative API specifications were starting to become popular, but remained fairly unapproachable. You could use documentation-focused Swagger (which later became OpenAPI) or modeling-centric RAML. In either case, you had to write the YAML or JSON yourself, which significantly increased the barrier to entry for many would-be adopters.
We built the first visual API designer to enable anyone to design an API without first picking and learning a new specification syntax. You could bring an existing document, or start fresh with a builder that walks you through the elements of an API definition. Model request and response shapes, declare HTTP methods, and so on. Many of the ideas in this groundbreaking initial interface remain in Stoplight Studio.
Our first API design tool saved valuable developer time and opened the design process up to the whole team. Without becoming a Swagger or RAML expert, enterprise architects and product managers alike could build APIs 10x faster than using a code based editor.
When OpenAPI emerged as the industry choice, we wanted our design editor to fully support the format. In 2018, we built the next version of our designer to adopt this standard. While our original designer supported multiple API specifications, it deconstructed and reconstructed them on import/export. This was a lossy process, and any non standard OpenAPI (such as extensions) was lost when rebuilt. Our second API designer improved upon this flaw with a lossless approach - it operated directly on the original OpenAPI document. Because it worked directly with the underlying specification document, it was the first time we supported both a form AND code editor experience.
Our customers build and update many APIs, which brings a versioning challenge. We attempted to solve the problem with a tool well known for branching and merging. Our new editor was built atop a Gitlab server that we host, which allowed for tracking revisions and defining versions. Any team member could use the editor, add comments, make updates, and see all the changes. Our customers love the experience and insight it gives them into their API design and development process. Plus, we gave them tools to share their API beyond the immediate team.
Our API design application had solved many of our customer’s problems, but we inadvertently created yet another walled garden. The Gitlab that we run to power many of the git features became the source of truth for our customer’s design assets. Customers could not leverage their existing version control systems, and in order to get the maximum benefit, everyone in their organization needed to store their design assets on our servers.
With Stoplight Studio, our aim is to become part of your workflow, rather than requiring you to conform to ours. We connect to your git server, and bring the lossless OpenAPI visual editor you’ve come to expect. Changes are saved locally until you choose to push them to your repository. We can also detect external changes so you’re always working with the latest version.
OpenAPI documents can be leveraged across the API lifecycle. Our team contributes to many open source projects in API tooling area, including some we’ve created ourselves. Two of these are bundled with Stoplight Studio:
We invite you to try Stoplight Studio now. Both Studio Web and Studio Desktop are free. You can open any GitHub URL inside the editor and begin to explore how we interpret your API files. Prototype new endpoints, generate mock servers, and quickly publish documentation.
Stoplight Studio is the first of a broader set of tools from Stoplight to help organizations go design-first with their APIs. We’ve got many other exciting updates and features in the pipeline, and can’t wait to share them. Until then, happy designing!
Bundling, dereferencing, and how to use them in Stoplight Studio and CLI workflows.
Mar 11, 2020