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
| Path | Holds |
|---|---|
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.json | The sidebar of the published docs, written by hand |
.stoplight.json | Project configuration: which folders hold which format |
.spectral.json, .spectral.mjs, .stoplight/styleguide.json | Style 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 Markdown | In an APIGit Markdown page |
|---|---|
<!-- theme: warning --> before a blockquote | A 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 group | A Code Group component |
A json_schema code block, or one with a $ref to a model | The 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 matter | Not used by APIGit; remove it once the Stoplight project is switched off |
| Mermaid diagrams, images, tables | Unchanged |
Search the docs/ folder for <!-- to find every annotation.
7. What changes for your readers
| In Stoplight | After 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 Stoplight | On 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 permissions | Set 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
- Stoplight documentation, work with files (project directories)
- Stoplight documentation, configure projects (.stoplight.json)
- Stoplight documentation, project sidebar (toc.json)
- Stoplight documentation, export files (Download Project Zip)
- Stoplight documentation, Stoplight Flavored Markdown
- Stoplight documentation, work with mock servers
- Stoplight documentation, style guides and Git
- Stoplight documentation, project overview (supported formats)
- Stoplight documentation, Stoplight URLs (stable ids, published addresses)
- Stoplight documentation, Git overview (providers)
- APIGit documentation, create or migrate a repository
- APIGit documentation, navigation (apigit.json)