Uploading a Schema

Supported formats

Mockra accepts OpenAPI specs in the following formats:

Format	Supported versions
YAML	OpenAPI 3.0, 3.1, Swagger 2.0
JSON	OpenAPI 3.0, 3.1, Swagger 2.0

Both openapi: "3.x.x" and swagger: "2.0" documents are supported. Internal $ref references are resolved automatically.

---

Upload methods

File upload

Drag and drop a .yaml, .yml, or .json file onto the upload area in the dashboard, or click to browse your filesystem.

Maximum file size: 5 MB.

URL fetch

Enter the URL of a publicly accessible OpenAPI spec. Mockra fetches the file at upload time and stores it. The URL is not polled after upload — use Schema Drift Detection if you want to monitor for upstream changes.

Example URLs that work:

https://raw.githubusercontent.com/org/repo/main/openapi.yaml
https://petstore3.swagger.io/api/v3/openapi.json

Raw paste

Click "Paste spec" and enter YAML or JSON directly into the text area. Useful for small specs or quick experimentation.

---

What happens after upload

1. Mockra validates and parses the spec
2. All paths × HTTP methods with defined responses are extracted as endpoints
3. A mock config is created for each endpoint with a default response generated from the spec
4. The mock configs are written to the edge cache — endpoints are immediately live

The default response uses the first 2xx status code defined for that endpoint. The response body is generated from:

• The example field in the response schema (if present)
• Auto-generated example values from the schema type definitions

---

Auto-generated examples

Mockra generates response bodies from your OpenAPI schema when no explicit example is provided. The generation rules are:

Schema type	Generated value
string	"string"
integer	0
number	0.0
boolean	true
array	[<item example>]
object	{ <property: example>, ... }

If your schema has an example or examples field, that value is used as-is.

---

$ref resolution

Mockra resolves internal $ref references within the same document. This includes:

• #/components/schemas/... references in OpenAPI 3.x
• #/definitions/... references in Swagger 2.0
• Nested refs (refs that point to objects containing other refs)

External $ref references (pointing to other files or URLs) are not resolved. Bundle your spec into a single file before uploading if it uses external refs.

---

Managing schemas

View endpoints

After uploading, click a schema name to see all endpoints Mockra detected. Each endpoint shows:

• The HTTP method and path
• The default response status code
• A link to edit the mock config

Delete a schema

Deleting a schema removes it and all its mock configs. The mock endpoints stop responding immediately. This cannot be undone.

---

Limits by tier

Tier	Max schemas	Max endpoints
Free	2	5
Starter	10	50
Pro	1,000	1,000
Enterprise	Custom	Custom

If you exceed the limit for your tier, the upload will fail with a 403 response. You can delete an existing schema to make room, or upgrade your plan.

---

Troubleshooting

"Invalid OpenAPI document" — The spec failed validation. Common causes: missing info or paths fields, invalid YAML syntax, unsupported version.

"Failed to fetch URL" — The URL is not publicly accessible or returned a non-200 status. Check that the URL works in a browser without authentication.

"Schema limit reached" — You've hit the maximum number of schemas for your tier. Delete an existing schema or upgrade.

$ref not resolved — An external ref was found. Bundle the spec into a single file (tools like swagger-cli bundle or redocly bundle can help).