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/p), 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.
Feature Comparison
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
- Documentation
- Mocking
- Testing
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.
API Design + Modeling
| Feature | Classic | Next | Platform/Studio |
| Form-based editing of Swagger/OpenAPI v2 | X | X | X |
| Form-based editing of OpenAPI v3 | X | ||
| Edit and store raw specifications in JSON format | X | X | |
| Edit and store raw specifications in YAML format | X | ||
| Store project files directly in custom Git repository | X | ||
| Full offline editing support | 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/private | X | ||
| CRUD builder for generating API endpoints | X | X | Planned |
| Generate examples from JSON schema | X | X | Planned |
| Generate JSON schema from sample JSON | X | X | Planned |
Documentation
| Feature | Classic | Next | Platform/Studio |
| OpenAPI support | X | X | X |
| Markdown support | X | X | X |
| Request Maker | X | X | X |
| Build history & instant rollbacks | X | X | |
| White labeling | X | X | X |
| SAML Integration | X | X | |
| Theming | X | X | April 2020 |
| Custom navigation | X | X | April 2020 |
| Custom domain | X | X | April 2020 |
| Custom CSS | X | X | |
| Custom Javascript | X | X | |
| Basic Auth Integration | X | X | |
| auth0 Integration | X | X | |
| Download static HTML/CSS/JS | X | ||
| HTTP request OAuth token manager | X | ||
| Javascript web component support for embedding Stoplight-hosted documentation into larger websites | X | ||
| Generated Table of Contents per article | X |
Mocking
| Feature | Classic | Next | Platform/Studio |
| Create a virtualized mock server from OpenAPI specification |
X |
X |
X |
| Mock multiple OpenAPI specifications at once | X | X | |
| Dynamically generate responses from JSON schema | X | X | X |
| Proxy traffic to live API server | X | ||
| Extend mock behavior with custom Javascript | X | X | |
| Run mock servers locally from Prism CLI | X | X |
Testing
| Feature | Classic | Next | Platform/Studio |
| 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 |
X |
||
| Use custom Javascript to extend testing capabilities | X | ||
| Generate coverage reports based on connected OpenAPI v2 descriptions | X (OAI v2 only) |
||
| Issue tests from Prism CLI | X |