Stoplight's latest API Design Management platform offers a new design interface, native OpenAPIv3 support, advanced Git integration, and more. This article discusses the differences in functionality for users coming from Stoplight Classic or Stoplight Next who are looking to migrate to the latest version of Stoplight.
A Brief History Lesson
Since Stoplight was initially founded, there have been three different generations of the API design application that have been created:
- Classic - Stoplight "Classic" (app.stoplight.io) is the first iteration of the Stoplight platform, and is now considered legacy. No new users, payment subscriptions, or enhancements will be added to the Classic application. You should only be using Stoplight Classic if you already have an account with a workspace.
- Next - Stoplight "Next" (next.stoplight.io) is the second iteration of the Stoplight platform. Next includes functionality such as Hubs and Scenarios, in addition to the API Designer and Documentation features that are available in the latest Stoplight generation.
- Platform - Available at (stoplight.io/welcome), this is the latest and greatest version of the Stoplight API Design platform, which includes Studio (with native Git, OpenAPIv3 support), Explorer, Prism v3, and more. This version is where all new features and functionality will land moving forward.
Our product roadmap can be found here.
The latest iteration of Stoplight was built from the ground up to be an extensible, easy-to-use platform for building, sharing, and managing your API designs and design-related artifacts. To that end, the new platform + Studio does not yet have some of the features that are currently provided with Stoplight's Next or Classic product. The functionality in Classic and Next typically fits into four areas of focus:
- API Design + Modeling
Before trying to migrate to the new platform, please review the sections below for any areas of functionality that are important to your use case.
Please note that this matrix was created from the perspective of users coming from older Stoplight products, so new functionality that was not available in previous products may not be included here for brevity.
API Design + Modeling
|Form-based editing of OpenAPI v2||X||X||X|
|Form-based editing of OpenAPI v3||X|
|Edit and store files in JSON format||X||X|
|Edit and store files in YAML format||X|
|Store project files directly in custom Git repository||X|
|Full offline editing support||X|
|Support for shared parameters/responses||X||X||X|
|Specification validation for syntax errors||X||X|
|Custom validation and lint rules||X||X|
|Store models in standalone JSON schema files||X|
|Markdown editing for API descriptions/summaries||X||X||X|
|Mark API endpoints as deprecated||X||X|
|Selectively hide endpoints with x-private||X|
|CRUD builder for generating API endpoints||X||X||roadmap|
|Generate examples from JSON schema||X||X||X|
|Generate JSON schema from sample JSON||X||X||X|
|Build history & instant rollbacks||X||X|
|Custom top-bar navigation||X||X|
|Custom base path (ie, "/docs")||X||X|
|Basic Auth Integration||X||X||X|
|auth0 Integration||X||X||(via SAML)|
|Google Tag Manager Integration||X||roadmap|
|Google Analytics Integration||X||roadmap|
|Download static HTML/CSS/JS||X|
|Set custom redirects||X||roadmap|
|Set environment variables||X||roadmap|
|HTTP request OAuth token manager||X||roadmap|
|Generated Table of Contents per article||X|
|Create a virtualized mock server from OpenAPI specification||
|Mock multiple OpenAPI specifications at once||X||X|
|Dynamically generate responses from JSON schema||X||X||X|
|Proxy traffic to live API server||X|
|Run mock servers locally from Prism CLI||X||X|
Deprecation Notice Testing functionality (powered by Scenarios) in Stoplight Next will not be carried forward into future products.
For testing needs, Stoplight recommends evaluating other tools in the testing space, such as Postman, Insomnia, and others. To see how such tools can be used in coordination with Stoplight's Prism mock server for request/response validation, please see the article here.
|Issue a series of HTTP requests against a live API||X|
|Create custom test assertions||X|
|Capture response data for use in later requests||X|
|Contract test API responses by comparing them with schema defined in OpenAPI v2/Swagger description||
|Generate coverage reports based on connected OpenAPI v2 descriptions||X
(OAI v2 only)
|Issue tests from Prism CLI||X|