Automatically Generate OpenAPI 3.0 Schemas from Mock API Responses using PHP

ka2 — Fri, 11 Apr 2025 07:07:24 +0000

If you've ever found yourself writing repetitive OpenAPI specs by hand, you'll love this.

What if your mock API server could auto-generate OpenAPI 3.0 schemas just from example responses?

That's exactly what MockAPI-PHP does.

🧩 What is MockAPI-PHP?

MockAPI-PHP is a lightweight, file-based mock API server written in PHP 8.3+.

It lets you simulate RESTful API endpoints using just .json or .txt files — no backend or framework required.

You can:

Define dynamic responses using simple files
Simulate polling, authentication, errors, and delays
Auto-generate OpenAPI 3.0 schemas from your response examples
Serve your mock API via browser or CLI — even integrate into CI/CD

🚀 Key Features

✅ JSON-based mock responses

✅ Dynamic parameters (/users/{group}/{limit})

✅ Response polling (per client)

✅ Built-in authentication (via .env)

✅ Schema validation using opis/json-schema

✅ Auto-generated OpenAPI files: YAML or JSON

✅ Simple CLI tool + PHP built-in server compatible

🧪 Example: Creating a Mock Endpoint

Let's say you want to mock the following:

GET /products → returns a list of products
POST /products → accepts a new product object
PUT /products → accepts a new product or already exists object
PATCH /products/{id} → accepts a product property updates
DELETE /products/{id} → accepts a product deletion
GET /products?mock_response=error → returns an error response for get method
POST /products?mock_response=error → returns an error response for post method
PUT /products?mock_response=error → returns an error response for put method

All you need to do is create this file structure:

responses/
 └── products/
     ├── get/
     │     ├── default.json
     │     └── error.json
     ├── post/
     │     ├── default.json
     │     └── error.json
     ├── put/
     │     ├── default.json
     │     └── error.json
     ├── patch/
     │     └── default.json
     └── delete/
            └── default.json

An example json file for get method:

[
    {
        "id": 1,
        "name": "Product A",
        "description": "Description of Product A",
        "price": 19.99,
        "category": "Electronics",
        "stock": 100,
        "created_at": "2025-04-01T12:00:00Z",
        "updated_at": "2025-04-01T12:00:00Z"
    },
    {
        "id": 2,
        "name": "Product B",
        "description": "Description of Product B",
        "price": 29.99,
        "category": "Books",
        "stock": 50,
        "created_at": "2025-04-02T12:00:00Z",
        "updated_at": "2025-04-02T12:00:00Z"
    },
    ...
]

Then start the server:

php start_server.php

And you're live on http://localhost:3030/api/products.

If the endpoint is a GET method, you can immediately check the response by accessing it directly in your browser.

The best way to check the responses of the various methods is to send requests to the endpoints in the CLI.

curl -X POST http://localhost:3030/api/products
{
  "status": "success",
  "message": "Product created successfully",
  "data": {
    "id": 1,
    "name": "Product Name",
    "description": "Product Description",
    "price": 19.99,
    "category": "Category Name",
    "stock": 100,
    "created_at": "2025-04-01T12:00:00Z",
    "updated_at": "2025-04-01T12:00:00Z"
  }
}

curl -X PATCH http://localhost:3030/api/products/1
{
  "status": "success",
  "message": "Product updated successfully",
  "data": {
    "id": 1,
    "name": "Updated Product Name",
    "description": "Updated Product Description",
    "price": 19.99,
    "category": "Updated Category Name",
    "stock": 100,
    "created_at": "2025-04-10T12:00:00Z",
    "updated_at": "2025-04-10T12:00:00Z"
  }
}

curl -X DELETE http://localhost:3030/api/products/1
{
  "code": 204,
  "message": "No Content"
}

📘 Bonus: Auto-Generate OpenAPI 3.0 Schema

Want to generate an OpenAPI spec file based on your current mock responses?

Just run:

php generate-schema.php yaml "My Awesome API" "1.0.0"

You'll get a schema/openapi.yaml file, ready to import into Swagger, Stoplight, or Postman.

It even embeds trimmed example data from your mock files.

If you preview the OpenAPI Schema file automatically generated from the response configuration in the previous section with SwaggerUI, it will look like this:

Conveniently, arrays in the JSON file registered as dummy responses are optimized as examples by trimming them to only the first element, which prevents the schema file from becoming too large.

🛠 Use Cases

API-first design: mock first, develop later
Frontend integration without waiting for backend
Testing various response types (success, error, timeout, etc.)
Validating schema structure for contract testing

🧩 Try It Now

GitHub: https://github.com/ka215/MockAPI-PHP
Requirements: PHP 8.3+, Composer
License: MIT

Thanks for reading! 🙌
If you find this tool useful, feel free to give it a ⭐️ on GitHub or share with your team.