Documents and base paths

A spec-based mock server serves one or more API documents from one commit of your repository. Each document is mounted under a base path, so several APIs can live on one mock server without their routes colliding.

https://petstore-sandbox.mockserver.apigit.com
├── /pets/v3    openapi/petstore.yaml
└── /orders/v2  openapi/orders.yaml

Supported documents

• OpenAPI 3.0.x and 3.1.x, in YAML or JSON
• Swagger 2.0, converted automatically
• Split documents: the local files a document references with $ref are collected with it, including files in other folders of the repository

A remote $ref (one with a URL) is refused at publish, because the mock fetches nothing from the internet. Inline or vendor those definitions into the repository.

Base paths

The default base path is the path part of the document’s first servers URL, for example /orders/v2 for https://api.acme.example/orders/v2. A document with no servers, or a URL with no path, defaults to /.

You can set any other base path, even for a single document. The document’s own servers path then plays no part in routing.

A base path:

• starts with /
• uses plain segments of letters, digits, ., _, ~ and -, with no {parameters}
• has no trailing slash, except / itself
• has at most 128 characters
• is unique within the mock server
• is not under /apigit-mockserver-, which is reserved for the built-in routes

How a request finds its document

The longest base path that matches whole path segments wins. That base path is removed, and the rest of the path is matched against the document’s operations.

Documents never share a route table, so two documents can both declare /pets under different base paths.

Change documents after publishing

Open the mock server, choose Setting, and use Documents & Base Paths. The section lists every OpenAPI file at the commit the mock serves.

• Check a document to add it, or uncheck one to remove it.
• Edit a base path.
• Turn each validation check on or off for a document.

Click Save documents. Changes apply without a republish, and the mock server keeps its URL and commit.

List what a mock serves

GET /apigit-mockserver-routes returns every document with its base path and operations:

curl https://petstore-sandbox.mockserver.apigit.com/apigit-mockserver-routes

{
  "message": "Mock Server routes list",
  "routes": ["GET /orders/v2/orders", "..."],
  "mounts": [
    {
      "kind": "openapi",
      "source": "openapi/orders.yaml",
      "base": "/orders/v2",
      "operations": [
        { "method": "GET", "path": "/orders/v2/orders", "operationId": "listOrders" }
      ]
    }
  ]
}

Limits

Mock server calls count toward your plan’s monthly quota, once per request.