Skip to content

Moving a Stoplight project to APIGit: what carries over, what to convert

Last checked and updated

A Stoplight project is made of ordinary files: OpenAPI descriptions, JSON Schema models and Markdown articles in a documented folder layout. The API files move to APIGit unchanged. Two things need converting: the sidebar file toc.json, and the Stoplight-specific annotations in Markdown pages. This page goes through each part on a sample project. Facts about Stoplight were read in its own documentation on 20 November 2026, and are linked under Sources (those pages open in a browser; some tools that fetch them without one get an error).

What is in a Stoplight project

PathHolds
reference/API descriptions: OpenAPI (2.0, 3.0, 3.1) and JSON Schema
models/Models, as JSON Schema files
docs/Articles, in Stoplight Flavored Markdown
assets/images/Images
toc.jsonThe sidebar of the published docs, written by hand
.stoplight.jsonProject configuration: which folders hold which format
.spectral.json, .spectral.mjs, .stoplight/styleguide.jsonStyle guide rules, when the project uses Git

1. Get the files

A Git project already lives in a repository on GitHub, GitLab, Bitbucket or Azure DevOps. Nothing has to be exported: the repository is the project.

A project that is not connected to Git keeps its data in Stoplight. Its documentation gives the way out: select the project, Edit, then Download Project Zip, which contains the API documents, models and Markdown articles. One thing to know, in the documentation's words: "Downloading projects resolves $refs in API and JSON Schema files." Compare a downloaded description with the one you edited before deciding which to keep.

2. Put them in an APIGit repository

For a Git project, create the repository in APIGit with the Migration option and give it the address of the existing one: an https:// address, with a token for a private repository on GitHub or Bitbucket. APIGit imports the content of that repository into the new one.

For a downloaded zip: create a blank repository in APIGit, clone it, unpack the zip into the clone, commit and push. Pushing over HTTPS asks for your user name and a personal access token.

3. The API files work as they are

A description in reference/ that refers to a model in models/:

# reference/orders.yaml
              schema:
                $ref: ../models/Order.yaml

lints and bundles without a change:

$ apigit lint reference/orders.yaml
reference/orders.yaml
  4:6  warn   info-contact  Info object must have "contact" object.  (info)

1 problem (0 errors, 1 warning, 0 info, 0 hints)

The local mock needs one extra step with this layout. Serving the file directly is refused, because the model it refers to lies outside the description's own folder:

$ apigit mock serve reference/orders.yaml
error: the document cannot be served: ... "orders.yaml: $ref target models/Order.yaml is not in the published documents"

Bundle first, and serve the bundle:

$ apigit bundle reference/orders.yaml -o bundled.yaml
Wrote bundled.yaml
$ apigit mock serve bundled.yaml --port 4677
$ curl http://127.0.0.1:4677/orders/1
{"id":"string","status":"open"}

We ran this with the command line only; check a hosted mock of your own project the same way before relying on it.

Stoplight writes stable ids into the files, x-stoplight: id: ... in API and model files. They are specification extensions: other tools ignore them, and they stay in the output of a bundle. Leave them in while the Stoplight project is still in use: its documentation says "you should never delete them", because the addresses of the published pages depend on them. Once the Stoplight project is switched off they have no function.

4. Style guide rules

Stoplight's style guides are Spectral rule sets, and the apigit command line lints with Spectral. Run from the project root, it picked up a .spectral.json there without being told. With this file in the sample project:

{
  "extends": ["spectral:oas"],
  "rules": { "operation-operationId": "error", "info-contact": "off" }
}

the same lint run reports No problems found.: the rule that warned before is now off. Run from another folder, the file is not found and the warning is back. A Git project often holds .spectral.mjs instead (Stoplight generates it from the imported rule sets and custom functions); that file is not picked up by itself: name it with apigit lint --ruleset .spectral.mjs, and test rules that use custom JavaScript functions one by one.

5. Convert the sidebar: toc.json to apigit.json

{
  "items": [
    { "type": "divider", "title": "Guides" },
    { "type": "item", "title": "Getting started", "uri": "docs/getting-started.md" },
    { "type": "divider", "title": "API reference" },
    { "type": "item", "title": "Orders", "uri": "reference/orders.yaml" }
  ]
}

becomes a navigation file in the repository root:

{
  "nav": [
    {
      "name": "Guides",
      "slug": "guides",
      "children": [
        { "name": "Getting started", "slug": "getting-started", "file": "docs/getting-started.md" }
      ]
    },
    {
      "name": "API reference",
      "slug": "api-reference",
      "children": [
        { "name": "Orders", "slug": "orders", "file": "reference/orders.yaml" }
      ]
    }
  ]
}

A divider followed by items becomes an entry with children; a group maps the same way. Without the file, a published site lists the repository's API and Markdown files in their natural order, so this step can wait. APIGit also has a form editor for the file.

6. Convert Stoplight Flavored Markdown

Standard Markdown carries over. The annotations Stoplight adds in HTML comments do not render elsewhere, and each has a counterpart:

Stoplight Flavored MarkdownIn an APIGit Markdown page
<!-- theme: warning --> before a blockquoteA callout: :::warning[Sandbox only] ... :::
A comment block with the lines type: tab and title: curl, closed later by <!-- type: tab-end --><Tabs> with one <Tab title="curl"> per tab
Adjacent code blocks shown as a tabbed groupA Code Group component
A json_schema code block, or one with a $ref to a modelThe Json Schema component, or a link to the model in the API reference
A json http request block (Try It)No counterpart in a Markdown page: link to the operation in the API reference, which has its own Try It
stoplight-id in the front matterNot used by APIGit; remove it once the Stoplight project is switched off
Mermaid diagrams, images, tablesUnchanged

Search the docs/ folder for <!-- to find every annotation.

7. What changes for your readers

In StoplightAfter the move
Published pages at .../docs/{project}/{id}-{title}New addresses. On your own domain, set a redirect per moved page in the site settings; pages that were on a Stoplight address cannot be redirected from your side
Mock servers at stoplight.io/mocks/{workspaceName}/{projectName}:{optionalBranchName}/{ID}New mock server addresses: update clients and CI. The Prefer: code=... and Prefer: example=... headers work the same way, since both follow Prism's conventions
A custom domain pointing at StoplightOn the Team and Enterprise plans: set the domain in the published site's Domain settings, then change its DNS record to APIGit when the new site is ready
Users, roles and permissionsSet up again: they are not part of the files

Before you switch off the old project

Publish the documentation from the new repository, open the pages that had annotations, call the mock with the requests your tests make, and run the linter with your rule set in CI. The old project can stay untouched until the new one has answered all four.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish