If your team is planning a Stoplight migration, you are probably not just replacing an OpenAPI editor.
In many Stoplight-based teams, the real API workflow is split across several places: Stoplight manages API documentation and OpenAPI specs, GitHub or GitLab stores the source files, Postman manages collections, environments, shared secrets, manual testing, and QA collaboration, while CI/CD keeps validation results in pipeline logs.
So the migration question is not simply “where do we import the OpenAPI file?” It is: how do you move the API contract, Markdown docs, reusable models, documentation navigation, Git review, request examples, tests, and team collaboration without rebuilding the whole workflow from scratch?
That is why a Stoplight migration should not start with a blank API project. It should start with the repository and project structure your team already depends on.
Apidog spec-first mode is built for that kind of migration path. It lets teams keep OpenAPI specs file-based, connect them to Git when needed, and bring the surrounding API work into a broader Apidog workspace for docs, mocks, tests, reports, permissions, and collaboration.
The goal is not to take specs out of Git. The goal is to keep the contract as the anchor while reducing the workflow fragmentation around it.
Why Stoplight Migration Is Harder Than OpenAPI Import
Migrating from Stoplight is not the same as importing one Swagger or OpenAPI file.
A Stoplight-style project often includes more than endpoints:
- OpenAPI files, often under a
referencedirectory; - Markdown documentation, often under
docs; - JSON Schema models, often under
models; - images referenced by documentation;
.stoplight.jsonfor project path configuration;toc.jsonfor navigation, grouping, and ordering;- Stoplight identifiers such as
x-stoplight-idorstoplight-id.
Those files carry project context. They describe not only what the API is, but also how the API project is organized and how people navigate it.
If migration only preserves endpoints, the team may still lose the structure that made the project usable. Docs may need to be rebuilt. Navigation may need to be recreated. Models may become harder to trace. Tests, mocks, and collaboration workflows may need to be reconnected manually.
A better migration plan treats the repository as the starting point.
The Workflow Most Stoplight Teams Are Trying to Preserve
Most Stoplight teams are not trying to abandon file-based API work. They are trying to keep the useful parts while removing the duplicated work that appears when specs, docs, client collections, test results, and team decisions live in separate tools.
The friction usually appears when one API change has to move through several tools.
The diagram below shows how one API change can either scatter across tools or move through a connected spec-first workflow.
| Workflow step | Before migration: Stoplight + Git + API client | After Apidog spec-first mode |
|---|---|---|
| Change the API contract | Update OpenAPI files in Git or Stoplight, then make sure published docs catch up | Keep OpenAPI files as the contract source in a Git-connected or file-backed spec project |
| Maintain docs and structure | Manage Markdown docs, navigation, models, and project paths through Stoplight-style files | Bring Markdown docs, models, .stoplight.json, and toc.json into the migration scope, then validate how each maps into the spec-first project |
| Update requests and tests | Maintain API client examples, environments, and manual tests separately from the spec | Rebuild request, mock, and test workflows around the connected OpenAPI contract |
| Keep standards and validation visible | Linting feedback, CI/CD logs, test results, docs links, and decisions are shared across separate tools | Real-time linting, docs, tests, reports, permissions, and collaboration can live around the same API project |
| Review future changes | Git may review the spec, while daily API collaboration happens elsewhere | Git-connected projects can sync, edit, commit, and push while Apidog supports day-to-day API work |
This is the workflow problem Apidog spec-first mode is meant to address. The API contract can remain file-based, but the work around the contract does not have to stay scattered.
What Apidog Spec-First Mode Changes
Apidog spec-first mode starts from files instead of a blank visual API project.
Teams can create a spec-first project from a Git repository, or start with a file-backed spec project before connecting external Git. Once the project is created, Apidog opens a Specs workspace where teams can browse, create, edit, and organize project files.
The basic migration model looks like this:
In practice, a Stoplight-style migration should account for common project assets such as OpenAPI specs, Markdown docs, JSON Schema models, images, .stoplight.json, and toc.json when present. These assets should be validated as project context, not treated as a one-file OpenAPI import.
The important shift is this: the files remain the foundation, but the team gets a workspace around them. That workspace can connect the contract to documentation, real-time linting feedback, mocks, test scenarios, CI/CD execution, reports, permissions, and collaboration.
What Happens to Stoplight-Style Project Files
The strongest migration path is to evaluate the project structure, not only the OpenAPI file.
| Stoplight-style asset | Why it matters in migration |
|---|---|
| OpenAPI specs | Source for API modules, endpoints, schemas, and examples |
| Markdown docs | Written documentation that lives beside the API contract |
| JSON Schema models | Reusable model definitions that should be validated after migration |
| Images | Documentation assets referenced by Markdown pages |
.stoplight.json | Project path configuration for specs, docs, models, images, and navigation files |
toc.json | Navigation order, grouping, and documentation structure |
| Linting and style rules | API design standards and validation feedback that should remain visible while teams review and edit specs |
| Stoplight IDs | Metadata to review during migration; they may remain in source files but should not be treated as a complete migration guarantee |
This is why a Stoplight migration should be evaluated at the project level. If your team already has a repository with specs, docs, models, images, and navigation files, that repository is the best starting point.
Git-Connected or File-Backed: Choose Your Starting Point
Not every team starts migration from the same place.
Some teams already have a mature repository-based workflow. Others have specs and docs as files but are not ready to connect an external Git provider during the first rollout.
Apidog spec-first mode supports both paths.
| Project type | Best for | Workflow |
|---|---|---|
| Git-connected spec project | Teams that already manage OpenAPI files in Git | Connect repo, sync branch, edit files, commit and push |
| File-backed spec project | Teams that want file-based spec management before connecting Git | Work with spec files inside Apidog and save changes |
For Git-connected teams, Git can remain the contract source while Apidog becomes the workspace for using and collaborating around that contract.
For teams earlier in the rollout, a file-backed spec project gives them a lower-friction way to validate the workflow before deciding how strictly external Git should govern daily changes.
What About API Client Assets?
Many Stoplight teams also have API client assets: request examples, environments, manual test flows, Postman collections, Bruno files, or internal scripts.
Those assets are important, but they are not the same thing as the OpenAPI contract.
During migration, separate the contract from the client workflow:
| Question | Migration implication |
|---|---|
| Where is the authoritative API contract? | Start with the OpenAPI files and project structure. |
| Which request examples or tests still matter? | Rebuild or migrate them around the connected API workspace. |
| Which environment variables or secrets are shared? | Plan how they should be managed in the new workflow. |
| Which reports or CI jobs need visibility? | Connect testing and reporting to the broader Apidog workflow. |
This keeps the migration realistic. Start with the source contract first, then reconnect request examples, tests, environments, and reports around that contract.
Stoplight Migration Checklist
Before moving a Stoplight-style project, review the project and workflow as a whole.
| Area | Questions to answer |
|---|---|
| Source of truth | Which repository, branch, and folder contain the authoritative OpenAPI files? |
| Project paths | Does the repo use .stoplight.json to define OpenAPI, docs, models, image paths, or navigation paths? |
| Navigation | Does the repo use toc.json for docs and API grouping? |
| Documentation | Which Markdown docs should be preserved? Are there images or internal links? |
| Models | Are JSON Schema models stored separately from OpenAPI specs? |
| Branch workflow | Should API changes happen through pull requests, Apidog editing, or both? |
| Client assets | Which request examples, test flows, or environment settings need to be rebuilt around the contract? |
| Rollout | Which teams need onboarding: backend, frontend, QA, platform, product, partners? |
The best migration plan does not move everything at once. It anchors the workflow around the API contract first, then connects docs, mocks, testing, reports, and collaboration around it.
When This Migration Path Makes Sense
Apidog spec-first mode is a strong fit for Stoplight migration when:
- your Stoplight project already uses OpenAPI files, Markdown docs, models,
.stoplight.json, ortoc.json; - your team wants Git or file-based specs to remain the source of truth;
- your docs, mocks, tests, reports, and collaboration workflows are currently split across tools;
- you want to move the workflow without treating migration as a one-time OpenAPI import.
It is not necessary to migrate every surrounding asset on day one. The first job is to preserve the API contract and project structure. The second job is to reconnect the daily API workflow around that contract.
FAQ
Is Apidog spec-first mode a Stoplight alternative?
It can be used as a Stoplight alternative for teams that want to manage OpenAPI projects as files while adding a broader API collaboration and execution workflow around those files.
Can I keep OpenAPI specs in Git?
Yes. For Git-connected projects, Git can remain the source of truth. Teams can sync a branch, edit specs, and commit changes back to the repository.
Do I need Git to start?
No. Teams can also start with a file-backed spec project and save changes inside Apidog. This is useful when you want file-based spec management before connecting an external Git provider.
What happens to Markdown docs and Stoplight-style project files?
Markdown docs, JSON Schema models, images, .stoplight.json, and toc.json should be reviewed as part of the project context. That is why migration should start from the repository structure, not only from one OpenAPI file.
Conclusion
Stoplight migration should not mean giving up file-based API work.
For many teams, the repository is still the right source of truth. OpenAPI specs, Markdown docs, JSON Schema models, and project structure files should remain portable and reviewable.
But the API workflow around those files can be better connected.
Apidog spec-first mode gives Stoplight teams a practical migration path: keep OpenAPI specs as files, review Stoplight-style project context during migration, and connect the contract to a broader API workspace for docs, mocks, testing, reports, permissions, and collaboration.
Planning a Stoplight migration? Talk to Apidog Enterprise about bringing your OpenAPI specs, docs, mocks, tests, and collaboration into a spec-first workspace.
You can also try Apidog and create a spec-first project from files or Git to evaluate the workflow yourself.
