Stoplight to Apidog Migration Guide: Managing OpenAPI Specs in Spec-First Mode

Migrating from Stoplight to Apidog is more than importing one OpenAPI file. You need to move a file-based API workflow that may include specs in Git, Markdown docs, JSON Schema models, local images, toc.json navigation inputs, and .stoplight.json path settings.

Try Apidog today

A Stoplight project may also depend on Postman request examples, Bruno files, CI test scripts, mocks, and publishing workflows. Importing only an OpenAPI file preserves endpoint definitions, but it does not automatically preserve the workflow around them.

Apidog Spec-first Mode helps teams keep OpenAPI files as the source of truth during a Stoplight migration while connecting those files to docs, mocks, tests, reports, permissions, and collaboration.

This guide shows how to:

1. Audit a Stoplight-style repository.
2. Carry over portable project files.
3. Review Stoplight-specific behavior.
4. Rebuild workflow-level assets.
5. Connect the OpenAPI contract to the broader API lifecycle.

For operational setup instructions, see the Spec-first Mode help guide.

Why Stoplight Migration Is More Than an OpenAPI Import

An OpenAPI file defines an API contract. A Stoplight-style project typically includes additional files and conventions around that contract.

Common project assets include:

• OpenAPI or Swagger files, often under reference or another configured directory
• Markdown documentation, often under docs
• JSON Schema model files, often under models
• Local images referenced by documentation
• .stoplight.json path configuration
• toc.json documentation navigation, grouping, and ordering inputs
• Stoplight identifiers such as x-stoplight-id or x-stoplight.id

If you import only one spec file, you may keep endpoints but lose important context:

• Documentation may need to be rebuilt.
• Navigation may not match the existing project.
• Models may become disconnected from docs.
• Tests, mocks, and request examples may remain in separate tools.

Start from the repository tree—not from a single OpenAPI file.

---

Migration Model: Carry Over, Review, Rebuild, Connect

Before migration, identify the actual source of truth.

If OpenAPI files in Git define the API contract, start with Spec-first Mode. If Postman or Bruno collections define the real request workflow, resolve that mismatch before moving the project.

Do not try to preserve everything exactly. Some Stoplight-specific behavior does not map one-to-one to another workspace.

Use this four-part model instead:

Category	What belongs here	Migration stance
Carry over	OpenAPI files, supported .stoplight.json path settings, supported toc.json navigation inputs, Markdown docs, referenced local images, and JSON Schema models where supported	Bring file-based project context into Spec-first Mode
Review	Markdown links, anchors, images, TOC grouping, schema naming, external $refs, Stoplight IDs, generated pages, and rendering differences	Verify the migrated workspace before treating it as production-ready
Rebuild	Postman or Bruno request flows, environments, manual tests, mocks, CI jobs, and publishing rules maintained outside the spec project	Recreate these around the OpenAPI source of truth
Connect	API docs, mock APIs, tests, CI reports, permissions, team collaboration, and partner workflows	Use Apidog to make the contract useful across the API lifecycle

Stoplight migration has two distinct layers:

1. File layer: OpenAPI specs, Markdown docs, models, images, and project structure files. This is where Spec-first Mode is directly useful.
2. Workflow layer: API reviews, publishing, tests, mocks, reports, permissions, and collaboration. Treat this as a separate migration concern.

The goal is not only to import data. It is to connect the contract to the workflow your team needs.

---

How Apidog Spec-first Mode Fits Stoplight Projects

Apidog Spec-first Mode supports file-based API workflows.

With a Git-connected project, your repository and branch remain the source of truth, while Apidog syncs with those files.

With a file-backed project, you can work with spec files directly in Apidog first, then connect Git later.

The Specs workspace gives your team one place to manage source files, inspect parsed API structures, and edit API definitions.

The Specs workspace lets teams manage source files, parsed API structure, and editing workflows in one place.

Map Stoplight assets to Apidog

Stoplight asset	What happens in Apidog	What to review
OpenAPI / Swagger files	Can be imported and synced as API modules, endpoints, schemas, and examples	Bundled references, conversion warnings, module names, and endpoint grouping
.stoplight.json	Supported fields can help locate OpenAPI, Markdown, and JSON Schema roots; apply OpenAPI include patterns and global excludes; and resolve tocPath	Treat it as path discovery for sync, not full Stoplight project configuration
toc.json	Can help create DOCS folders from supported groups and dividers, filter and order Markdown docs, apply titles, link folders to OAS modules or spec items, and import referenced JSON Schema models where supported	Review the final Apidog sidebar because exact Stoplight navigation and arbitrary cross-type ordering may not be preserved
Markdown docs	Documentation can be carried into the project workflow; TOC-listed docs can retain more structure where supported	Internal links, anchors, formatting, missing files, and rendering differences
Local images	Images referenced by Markdown can be imported where supported	Broken references, external images, data URIs, and unreferenced images
JSON Schema models	Explicitly referenced schema files, such as files referenced in toc.json, can be carried into Models where supported	Schema format, naming, grouping, references, and whether all models should be imported
Stoplight IDs	Root-level Stoplight IDs may help match imported modules across syncs	Do not assume endpoint-level or page-level identity is fully preserved

Compatibility notes for Stoplight project files

• Treat .stoplight.json as a supported path-configuration subset for sync. Apidog can use supported OpenAPI, Markdown, and JSON Schema root directories, OpenAPI include patterns, global exclude patterns, and tocPath.
• Treat other Stoplight project settings as ignored unless you verify their behavior after import.
• Use toc.json to migrate supported navigation semantics, including DOCS folders, Markdown ordering, OAS/module links, selected spec-item links, and TOC-referenced model imports.
• Review the final sidebar in Apidog. It uses the DOCS/OAS/MODELS model, so exact Stoplight layouts and arbitrary cross-type ordering may not be preserved.
• Verify images separately. Referenced local images are the most predictable migration case; unreferenced assets, external images, and data URIs need manual review.
• Reference JSON Schema files explicitly through supported project structures such as toc.json. Do not assume every file in a models directory becomes a model resource.

The target is not a pixel-perfect Stoplight recreation. The target is a portable, file-based project context connected to a broader API lifecycle.

---

From File Import to a Connected API Workflow

A traditional import workflow often imports an OpenAPI file once and then continues with visual edits in a new tool. That can create drift between:

• The OpenAPI files in Git
• Published documentation
• The API workspace
• Tests and mocks

Spec-first Mode keeps files at the center of the workflow.

In a Git-connected Spec-first project, teams can edit files in the Specs workspace, commit changes, and push them back to the repository.

In a file-backed project, teams can edit and save spec files in Apidog before connecting Git.

Use this responsibility split:

Responsibility	Recommended source
API contract	OpenAPI / Swagger files
Project file structure	Repository or file-backed project tree
Supported Stoplight-style path settings	.stoplight.json
Supported documentation navigation inputs	toc.json and Markdown docs
Daily API collaboration	Apidog project workspace
Mocks, tests, reports, and team permissions	Broader Apidog platform workflow

This is the main migration benefit: retain a file-first contract model while providing a usable API workspace for backend, frontend, QA, product, platform, and partner teams.

---

Git-Connected vs. File-Backed Migration Paths

Stoplight teams may start from different levels of Git maturity.

Some teams already review API changes through branches and pull requests. Others store API specs and docs as files but want to validate the workflow before connecting an external Git provider.

Apidog Spec-first Mode supports both paths.

Path	Best for	Typical workflow
Git-connected Spec-first project	Teams already managing OpenAPI specs in Git	Connect the repository, sync a branch, edit files, commit, and push
File-backed Spec-first project	Teams that want file-based API design before connecting Git	Work with spec files in Apidog, save changes, and validate the workflow first

For most Stoplight migrations, a Git-connected project is the clearer long-term approach because the repository remains the contract source of truth.

Use a file-backed project when you need to evaluate the authoring workflow, clean up project files, or stage the migration before adopting a stricter Git process.

---

What to Review After Migration

Even when files are carried over, run a structured review before using the migrated workspace in production.

Area	What to check
OpenAPI modules	Confirm all intended spec files were imported, module names are correct, and endpoints are grouped as expected
External references	Check whether $ref dependencies resolved correctly and whether conversion issues were reported
Lint and validation	Run Apidog Specs validation on imported OpenAPI files
.stoplight.json	Confirm supported OpenAPI, Markdown, and JSON Schema roots, include patterns, global excludes, and tocPath
toc.json	Review groups, dividers, titles, Markdown filtering and ordering, clickable groups, OAS links, selected spec-item links, model imports, and final sidebar output
Markdown docs	Check formatting, headings, relative links, anchors, and links to API files or operations
Images	Confirm referenced local images render correctly; review external images, data URIs, broken references, and unused assets separately
Models	Confirm which toc.json-referenced JSON Schema files became model resources and whether names, folders, and references are correct
Stoplight IDs	Confirm module matching behaves correctly across repeated syncs; do not rely on IDs for every resource type
Tests and mocks	Rebuild or reconnect workflows previously maintained in Postman, Bruno, CI, or separate tooling
Permissions and publishing	Recreate team access, documentation visibility, review rules, and release responsibilities

For validation, Apidog can use root-level Spectral configuration files:

.spectral.yaml
.spectral.yml
.spectral.json
.spectral.mjs

It can also fall back to .stoplight/styleguide.json for Spectral-based editor validation.

Treat validation results as review signals. Passing validation does not prove that every Stoplight-specific behavior was preserved.

---

What About Postman and Bruno Assets?

Many Stoplight teams also use Postman or Bruno. Plan those assets separately from the OpenAPI project migration.

OpenAPI files define the contract. Postman collections and Bruno .bru files usually define request workflows, examples, environments, or tests. These are valuable assets, but they are not the same migration object as a Stoplight-style OpenAPI project.

Answer these questions before migration:

Question	Why it matters
Is OpenAPI the source of truth, or are collections driving actual API behavior?	Spec-first migration should begin from the authoritative contract
Which request examples still matter?	Rebuild important examples around the connected API workspace
Which tests must keep running?	Move or reconnect tests instead of assuming they migrate with documentation
Which environments and secrets are shared?	Plan environment management separately from spec migration
Which CI jobs depend on current tooling?	Reconnect validation, testing, and reporting intentionally

For Bruno users, Git-native workflows are already valuable. Spec-first Mode can keep your API contract file-based, but Bruno assets may need separate migration, rebuilding, or replacement based on how your team uses them.

---

Recommended Migration Plan

Use a staged plan instead of attempting to migrate every workflow at once.

A staged migration plan: move the OpenAPI contract first, then reconnect the surrounding workflow.

1. Audit the Stoplight-style repository

Inventory:

• OpenAPI files
• .stoplight.json
• toc.json
• Markdown docs
• JSON Schema models
• Local images
• Postman collections or Bruno files
• CI scripts, tests, and publishing configuration

2. Decide the source of truth

Confirm that OpenAPI files in Git define the API contract.

If a Postman collection or Bruno workflow is effectively the source of truth, resolve that before starting a Spec-first migration.

3. Create the Spec-first project

Choose a Git-connected project when the team is ready to keep Git as the source of truth.

Choose a file-backed project when the team wants to validate the file-based workflow before connecting Git.

4. Review carried-over files

Check:

• Imported API modules
• Markdown documentation
• JSON Schema models
• Referenced images
• Internal links and anchors
• Supported toc.json navigation inputs
• Supported .stoplight.json path settings
• Specs validation results

Fix source project files where possible instead of manually patching symptoms in the workspace.

5. Rebuild workflow-level assets

Reconnect or recreate:

• Mocks
• Test scenarios
• Request examples
• CI jobs
• Reports
• Permissions
• Documentation publishing responsibilities

6. Run one real API change through the new workflow

Use a small, low-risk OpenAPI change to verify the full path:

1. Update the OpenAPI file.
2. Review the change.
3. Sync or commit it.
4. Update documentation if required.
5. Validate downstream mocks, tests, and reports.

If your team already maintains OpenAPI files, Markdown docs, and schema models in a Stoplight-style repository, this approach lets you validate the migration path before rebuilding the complete workflow.

---

When This Migration Path Fits Best

This path is a good fit when:

• Your team manages OpenAPI or Swagger specifications as files.
• Your Stoplight project includes Markdown docs, models, images, .stoplight.json, or toc.json.
• Your API review process depends on Git branches or pull requests.
• You want docs, mocks, tests, reports, and collaboration connected to the API contract.
• You want to reduce drift between API files and the workspace used by frontend, QA, product, platform, or partner teams.

It may require more planning when:

• A Postman or Bruno collection is the real source of truth rather than OpenAPI.
• The Stoplight project relies heavily on custom publishing behavior.
• Documentation includes many external links, anchors, generated pages, or unreferenced assets.
• JSON Schema models use formats or structures that need manual review.
• The team expects a pixel-perfect recreation of Stoplight navigation or rendering.

---

FAQ

Is Apidog Spec-first Mode a Stoplight alternative?

It can be used as a Stoplight alternative for teams that want to keep OpenAPI projects file-based while adding API collaboration, testing, mocking, documentation, reporting, and permission management around those files.

Can I keep OpenAPI specs in Git?

Yes. In a Git-connected Spec-first project, teams can keep Git as the source of truth, sync a branch, edit files, and commit changes back to the repository.

Do I need Git to start?

No. Use a file-backed Spec-first project to work with spec files first, then connect Git later.

Are .stoplight.json and toc.json fully preserved?

No. Apidog uses supported parts of these files as migration inputs.

.stoplight.json is primarily used for path discovery during sync, including supported OpenAPI, Markdown, and JSON Schema roots, OpenAPI include patterns, global excludes, and tocPath.

toc.json can help organize supported DOCS content, OAS/module links, selected spec-item links, and TOC-referenced model imports.

The final online documentation sidebar is constrained by Apidog's DOCS/OAS/MODELS model, so exact Stoplight navigation and arbitrary cross-type ordering may not be preserved.

What happens to Markdown docs?

Markdown docs can be carried into the Spec-first project workflow. When toc.json is present, TOC-listed docs can retain more structure where supported.

Review internal links, anchors, images, and rendering after migration.

What happens to JSON Schema models?

JSON Schema models can be carried over where supported when they are explicitly referenced through supported project structures, such as toc.json.

Do not assume every JSON file in a models directory automatically becomes a model resource. Review schema formats, names, folders, and references after migration.

What happens to images?

Local images referenced by Markdown can be imported where supported.

Do not treat formats.image.rootDir as a guarantee that every image file in that directory will be imported. Review external images, data URIs, broken references, and unused image files separately.

Should I run lint or validation after migration?

Yes. Run Specs validation on imported OpenAPI files.

Apidog supports Spectral-based editor validation and can read root-level .spectral.yaml, .spectral.yml, .spectral.json, and .spectral.mjs files, or fall back to .stoplight/styleguide.json.

Use the results to review contract and style issues. Do not treat successful validation as proof that every Stoplight-specific behavior was preserved.

What should Bruno or Postman users do?

First identify whether OpenAPI or collections are the source of truth.

Spec-first migration centers on OpenAPI and related project files. Collection-based request workflows, environments, and tests may need separate migration or rebuilding.

Does Apidog support mocks, tests, CI/CD, reports, and collaboration?

Yes. Spec-first Mode connects the file-based API contract to Apidog, while the broader platform can support documentation, mocks, test scenarios, CI/CD execution with Apidog CLI, reports, permissions, and team collaboration.

---

Conclusion

Stoplight migration does not require giving up file-based API work.

Keep the repository as the source of truth. Preserve portable project files where supported, including OpenAPI specs, Markdown docs, referenced images, TOC-referenced JSON Schema models, and supported project structure files.

Then rebuild and connect the workflow around those files.

Apidog Spec-first Mode provides a practical path: carry over supported file-based assets, review Stoplight-specific structures carefully, and reconnect API docs, mocks, tests, reports, permissions, and collaboration around a shared API contract.

For enterprise migration planning, see Apidog Enterprise.