How to Migrate from Stoplight to Apidog (Spec-First Workflow)

If you’re migrating from Stoplight Studio or Stoplight Platform to Apidog, treat the move as a Git-backed configuration change, not a full API-spec migration. Your OpenAPI YAML/JSON files can stay in the same GitHub or GitLab repo, while Apidog Spec-First Mode connects to that repo and reads the spec from Git. This walkthrough shows how to export any Stoplight-only assets, map Stoplight’s repo layout to Apidog, and replace .stoplight.json and toc.json with Apidog project settings.

Try Apidog today

Teams that already manage OpenAPI specs in Git alongside Stoplight documentation can usually keep their existing repo, branch strategy, and spec files. If you’re still comparing migration options, the top Stoplight Studio alternatives post covers the broader tooling landscape.

What stays the same when you migrate

Your core API assets do not need to change:

• OpenAPI YAML or JSON files
• GitHub or GitLab repo
• Branching strategy
• Commit history
• Existing $ref-based schema structure

Stoplight stores specs as YAML or JSON files in source control. Apidog reads those same files when you connect the repo in Spec-First Mode.

What changes is the tooling around the spec:

Area	Stoplight setup	Apidog setup
API docs	Stoplight documentation renderer	Apidog documentation
Mocking	Stoplight mock server	Apidog mock server
Testing	Stoplight tests or separate tools	Apidog test runner
API client	Often handled separately	Built into the Apidog workspace
Source of truth	Git repo	Same Git repo

The practical result: you are replacing Stoplight-specific configuration, not rewriting your OpenAPI definition.

Step 1: Export your Stoplight project assets

Start by identifying what Stoplight stores in Git and what it stores only in the Stoplight UI.

If you use Stoplight Studio with a Git backend

Your OpenAPI specs, JSON Schema models, Markdown docs, and assets are likely already committed.

Run:

git pull

Then inspect the repo layout. A common Stoplight project looks like this:

your-api-repo/
  .stoplight.json          # Stoplight project config
  reference/
    petstore.yaml          # OpenAPI spec files
  models/
    error.json             # Shared JSON Schema models
  docs/
    introduction.md        # Markdown guide pages
    authentication.md
  toc.json                 # Stoplight docs sidebar order
  assets/
    images/
      architecture.png

The OpenAPI files follow the OpenAPI Specification, so Apidog can read them without conversion.

If you use Stoplight Platform without a Git backend

Export each API project manually:

1. Open the API project in Stoplight.
2. Use Export to download the OpenAPI YAML.
3. Create a new GitHub or GitLab repo.
4. Add the exported specs to the repo.
5. Copy Markdown documentation into a docs/ directory.
6. Add image assets under assets/images/ or another stable folder.

Example target structure:

your-api-repo/
  reference/
    openapi.yaml
  docs/
    introduction.md
    authentication.md
  assets/
    images/
      architecture.png

Once the files are in Git, continue with the Apidog setup.

Step 2: Map Stoplight config to Apidog settings

Stoplight projects usually depend on two proprietary files:

• .stoplight.json
• toc.json

Apidog does not use either file directly. Instead, you configure the equivalent behavior in the Apidog project UI.

Stoplight file or convention	Purpose in Stoplight	How to handle it in Apidog
.stoplight.json	Defines project root, spec paths, docs paths, and included files	Configure repo, branch, and spec path in the Apidog project settings
toc.json	Controls documentation sidebar order and grouping	Use Apidog’s docs editor and sidebar settings
reference/	Common location for OpenAPI spec files	Point Apidog Spec-First Mode to the relevant spec file
models/	Stores shared JSON Schema models	Reference schemas from OpenAPI components/schemas with valid $ref paths
docs/	Stores Markdown guide pages	Import Markdown pages into Apidog Docs

You can leave .stoplight.json and toc.json in the repo during migration. Apidog ignores unknown files, so they will not block the setup.

Step 3: Connect your Git repo to Apidog Spec-First Mode

Apidog Spec-First Mode connects an Apidog project to a GitHub or GitLab repo. The OpenAPI file remains in Git, and engineers can continue updating it through pull requests.

If you are connecting a GitHub repo, review GitHub’s docs on authorizing GitHub Apps if your organization requires approval for third-party app access.

Connection flow

1. In Apidog, create a new project using Spec-First Mode.
2. Authenticate with GitHub or GitLab.
3. Select the repo that contains your OpenAPI file.

1. Select the branch:
   • Use main or master for production documentation.
   • Use a feature branch while testing the migration.

1. Set the path to your OpenAPI file, for example:

reference/petstore.yaml

1. Save the project.

Apidog reads the spec and generates interactive documentation, mock endpoints, and test scaffolding from the OpenAPI definition.

If your spec references files in models/, make sure the relative paths are valid from the spec file location.

Example:

components:
  schemas:
    Error:
      $ref: '../models/error.json'

If reference/petstore.yaml is one level below the repo root and models/error.json is at the repo root, this path is correct.

For more detail on Git sync behavior, see the sync OpenAPI spec to GitHub guide.

Step 4: Migrate your Markdown documentation

Stoplight supports Markdown guide pages alongside API reference docs. Apidog supports the same general workflow through its documentation editor.

To migrate Markdown pages:

1. Open your Apidog project.
2. Go to Docs.
3. Use Import > Markdown.
4. Upload your files from docs/, or paste content page by page.
5. Recreate the sidebar order in Apidog.

For images referenced from Markdown, check each image path.

Example Stoplight-style Markdown:

![Architecture](../assets/images/architecture.png)

If the image is local to the repo, upload it to Apidog’s file storage and update the Markdown reference. If the image is already hosted on a public CDN or URL, you can keep the existing URL.

Step 5: Replace Stoplight’s mock server

Stoplight Studio can run a local mock server from your OpenAPI spec. Apidog also generates mock endpoints from the OpenAPI definition, but the mock server is cloud-hosted and shared across the team.

After the repo is connected in Spec-First Mode, Apidog generates mock endpoints for operations in your spec.

Example OpenAPI response definition:

paths:
  /orders:
    post:
      summary: Create an order
      responses:
        '201':
          description: Order created
          headers:
            location:
              schema:
                type: string
          content:
            application/json:
              examples:
                created:
                  value:
                    id: ord_123
                    status: created

Apidog can use examples from the spec. If no example is defined, Apidog’s mock engine can generate mock data from the schema.

If your team currently runs:

stoplight mock reference/your-api.yaml

plan to replace local mock URLs with Apidog’s shared mock URL. Validate this during the trial if your organization has network access restrictions.

Step 6: Rebuild tests and keep linting in CI

Testing and linting need separate handling.

Keep Spectral linting in CI

Stoplight uses Spectral for OpenAPI linting, usually configured with a .spectral.yaml file.

Apidog has built-in OpenAPI linting, but it does not run Spectral directly. If your team depends on custom Spectral rules, keep them in CI.

Example GitHub Actions job:

name: OpenAPI lint

on:
  pull_request:
    branches: [main]

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Spectral
        run: |
          npx @stoplight/spectral-cli lint reference/petstore.yaml

This keeps your existing lint policy independent of the documentation and testing migration.

Rebuild API tests in Apidog

If you used Stoplight Platform scenario-based tests, rebuild them in Apidog’s test runner. There is no automated import path for Stoplight test projects.

In Apidog, create test scenarios that:

• Chain multiple requests
• Use variables between requests
• Assert status codes
• Assert headers
• Assert response body fields

Example test case to recreate:

POST /orders should return 201 and include a location header.

You can then run the Apidog test suite from CI with the Apidog CLI.

# .github/workflows/api-tests.yml
name: API contract tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog tests
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

For CI integration patterns, see the git-native API workflow guide.

Enterprise evaluation checklist

If you are migrating a larger team from Stoplight Platform, validate the following with a representative project before committing.

Capability	What to verify in Apidog
Private documentation access	Confirm whether documentation can be restricted to authenticated users or specific email domains based on your access-control requirements.
Schema/component reuse across projects	Test whether shared components/schemas files can be reused across projects without copy-pasting.
Custom lint rule sharing	If you rely on shared Spectral rules, verify how Apidog linting fits alongside your existing .spectral.yaml workflow.
SSO/SCIM provisioning	Confirm compatibility with your identity provider and user lifecycle process.
Audit logs	Review which events are logged and whether the format satisfies your security or compliance review.

Treat these as trial tasks. Most can be checked in one or two weeks using a real API project.

FAQ

Can I keep using Spectral with Apidog?

Yes. Keep .spectral.yaml in your repo and run Spectral in GitHub Actions, GitLab CI, or another CI system. Apidog handles documentation, mocking, and testing. Spectral can continue handling custom lint rules. See Spectral’s documentation for CI usage.

Will my $ref paths break when I connect the repo to Apidog?

They should not break if the paths are valid in your OpenAPI file. Apidog resolves $ref paths relative to the root OpenAPI file.

Example:

$ref: '../models/error.json'

If your spec is in reference/ and models/ is one level above it, this path should resolve correctly. Test with an API that uses external references before migrating all projects.

Does Apidog Spec-First Mode support GitLab as well as GitHub?

Yes. GitHub and GitLab are supported. The flow is similar: authenticate, select the repo, choose the branch, and set the spec path. For branch strategy guidance, see the OpenAPI version control with Git guide.

What happens to my existing Stoplight docs URL after migration?

Stoplight-hosted documentation URLs, such as docs.stoplight.io/your-org/your-api, stop working after you cancel the Stoplight subscription. Apidog provides a new documentation URL. If external users depend on the old links, configure redirects at your DNS, CDN, or reverse-proxy layer.

Do I need to delete .stoplight.json and toc.json?

No. Apidog ignores files it does not recognize. You can leave them in the repo during migration and remove them later in a cleanup pull request.

Conclusion

Migrating from Stoplight to Apidog is mostly a configuration swap. Keep your OpenAPI specs in Git, preserve your branch workflow, and map your existing reference/, models/, and docs/ directories into Apidog’s project setup.

A practical migration sequence is:

1. Pull or export your Stoplight assets.
2. Confirm the OpenAPI file and $ref paths are valid.
3. Connect the repo with Apidog Spec-First Mode.
4. Import Markdown docs.
5. Replace local Stoplight mocks with Apidog mock endpoints.
6. Rebuild test scenarios in Apidog.
7. Keep custom Spectral linting in CI if your team depends on it.

Start with one representative API project, validate the checklist above, then roll the workflow out to the rest of your repos. You can Download Apidog to begin.