Import from Stoplight

Use Apidog Spec-first Mode to migrate Stoplight-style OpenAPI projects while keeping your API specs as the source of truth. This is useful when your Stoplight project includes OpenAPI files, Markdown docs, JSON Schema models, images, .stoplight.json, toc.json, or Git-based workflows.

If you only need to import one OpenAPI file, see Import OpenAPI Spec. If you are comparing migration options, see Migration Guide Overview, Manual Import, and Import Options.

Before You Start

Review your Stoplight project files before creating the Apidog project.

Common files to check:

Asset	What to check
OpenAPI / Swagger files	Confirm which `.yaml`, `.yml`, or `.json` files are the source of truth.
Markdown docs	Identify docs that should be preserved. For standalone docs, see Import Markdowns.
JSON Schema models	Review reusable models and references. See Introduction to Schema and JSON Schema.
Images	Check local images referenced by Markdown docs.
`.stoplight.json`	Review project path configuration.
`toc.json`	Review documentation structure and ordering.
API client assets	Identify Postman, Bruno, test, environment, or CI assets that may need separate migration.

Start from the project repository or file tree, not just a single OpenAPI file.

Choose a Migration Path

Path	Best for	Workflow
Git-connected Spec-first project	Teams that already manage OpenAPI specs in Git	Connect a repository, sync a branch, edit files, commit, and push.
File-backed Spec-first project	Teams that want to validate file-based API work before connecting Git	Work with spec files in Apidog and save changes there.

For Git setup details, see Create a New API Project and Git Connection.

Create the Spec-first Project

Refer to the Spec-first Mode page for a more detailed instruction on Spec-first Mode project creation.

Click + New Project.

Select Spec-first Mode.

Connect a Git provider, such as GitHub, GitLab, or Azure DevOps, or choose a file-backed project.

If using Git, select the organization, repository, and branch to sync.

Choose whether to install a webhook.

Webhooks allow repository pushes to trigger sync automatically. Installing a webhook usually requires repository admin permission. You can skip this step and sync manually later.

Enter the project name, configure member permissions, and click Create.

After creation, Apidog opens the Specs workspace.

What Gets Migrated

Apidog can use supported Stoplight-style files as project context.

Asset	How Apidog uses it	Review after import
OpenAPI / Swagger files	Creates API modules, endpoints, schemas, examples, and docs.	Check module names, endpoint grouping, and references.
`.stoplight.json`	Uses supported path settings to locate specs, docs, models, images, and `toc.json`.	Confirm the configured roots match your repository. Check imported specs, docs, models, and images because not every Stoplight setting or include rule is applied the same way in Apidog.
`toc.json`	Helps arrange imported Docs/sidebar content and some OAS/model ordering during sync.	It does not reorder files in the Specs file explorer.
Markdown docs	Carries docs into the project workflow.	Check links, anchors, images, and formatting.
Local images	Imports referenced local images where supported.	Check for broken or unused images.
JSON Schema models	Carries referenced models where supported.	Check names, folders, and `$ref` behavior.

Review the Specs Workspace

In a Spec-first project, use the Specs workspace to manage files and Git sync.

The workspace includes:

File explorer: Browse files and folders.

API structure tree: Navigate parsed OpenAPI content, such as endpoints and schemas.

Editor: Edit files in code view or supported OpenAPI nodes in form view.

For related concepts, see Endpoint Basics, Module, and Components.

Validate and Preview

After import, validate the migrated files before using the project in production workflows.

Open the Specs workspace.

Select an OpenAPI or Swagger file.

Open the Validation panel.

Fix errors, warnings, broken references, or missing required fields.

Open Preview to check the generated API documentation.

For endpoints, Preview includes:

Docs: Generated endpoint documentation.

Try it out: A request panel based on the endpoint definition.

If you plan to test migrated endpoints, see Sending Requests, Environments & Variables in Apidog, and Using Variables.

Sync and Push Changes

Pull changes from Git

Open the Specs workspace.

Click the current branch name.

Click Git Pull.

If webhook sync is enabled, Apidog can also sync automatically after supported repository push events.

Push changes to Git

Edit files in the Specs workspace.

Click Changes.

Click Commit & Push.

Select the files to include.

Enter a commit message.

Click Push.

Use Discard all changes if you do not want to keep local edits.

Postman, Bruno, Tests, and CI

Stoplight migration focuses on OpenAPI and related project files. Postman collections, Bruno files, test scripts, environments, secrets, and CI jobs should be reviewed separately.

If you use Postman, see Import from Postman and How to migrate Postman environments to Apidog?.

For surrounding workflows, see:

Mock API Data in Apidog

Automated Tests in Apidog

Create a Test Scenario

CI/CD in Apidog

Introduction to Apidog CLI

Publishing Documentation Sites

Migration Checklist

Identify the authoritative OpenAPI files

Review project files and supporting assets

Review .stoplight.json, toc.json, Markdown docs, models, and images.

Choose project backing type

Decide whether to use a Git-connected or file-backed Spec-first project.

Create the Spec-first project

Validate imported OpenAPI files

Review documentation structure and assets

Review docs, links, images, schemas, and sidebar structure.

Reconnect project integrations

Reconnect mocks, tests, CI, publishing, and permissions as needed.

Test the new workflow

Run one small API change through the new workflow.

Notes and Limitations

Spec-first Mode is currently in beta.

The Specs workspace appears only in Spec-first projects.

.stoplight.json and toc.json are supported migration inputs, but they do not guarantee full Stoplight behavior preservation.

.stoplight.json uses supported path settings to locate specs, docs, models, images, and toc.json. This is path configuration only, not full Stoplight behavior preservation.

toc.json helps arrange imported Docs/sidebar content and some OAS/model ordering during sync. It does not reorder files in the Specs file explorer.

Exact Stoplight navigation and pixel-perfect documentation rendering may not be preserved.

Local images are primarily migrated when referenced by Markdown.

Postman, Bruno, CI, and custom publishing workflows may need separate migration or rebuilding.

FAQ

Is Apidog Spec-first Mode a Stoplight alternative?

Yes. It can be used by teams that want file-based OpenAPI projects with API documentation, testing, mocking, collaboration, and permission management around those files.

Can I keep OpenAPI specs in Git?

Do I need Git to start?

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

What happens to Markdown docs and images?

What happens to JSON Schema models?

Should I run validation after migration?

What should I do with Postman or Bruno assets?

Import from Stoplight

Before You Start#

Choose a Migration Path#

Create the Spec-first Project#

What Gets Migrated#

Review the Specs Workspace#

Validate and Preview#

Sync and Push Changes#

Pull changes from Git#

Push changes to Git#

Postman, Bruno, Tests, and CI#

Migration Checklist#

FAQ#

Before You Start

Choose a Migration Path

Create the Spec-first Project

What Gets Migrated

Review the Specs Workspace

Validate and Preview

Sync and Push Changes

Pull changes from Git

Push changes to Git

Postman, Bruno, Tests, and CI

Migration Checklist

FAQ