openapi-generator/samples/server/petstore/php-slim4/docs/MockServer.md

php-base - PHP Slim 4 Server library for OpenAPI Petstore

Mock Server Documentation

Mocker Options

To enable mock server uncomment these lines in index.php config file:

/**
 * Mocker Middleware options.
 */
$config['mockerOptions'] = [
    'dataMocker' => new OpenApiDataMocker(),

    'getMockResponseCallback' => function (ServerRequestInterface $request, array $responses) {
        // check if client clearly asks for mocked response
        if (
            $request->hasHeader('X-OpenAPIServer-Mock')
            && $request->getHeader('X-OpenAPIServer-Mock')[0] === 'ping'
        ) {
            if (array_key_exists('default', $responses)) {
                return $responses['default'];
            }

            // return first response
            return $responses[array_key_first($responses)];
        }

        return false;
    },

    'afterCallback' => function ($request, $response) {
        // mark mocked response to distinguish real and fake responses
        return $response->withHeader('X-OpenAPIServer-Mock', 'pong');
    },
];

• dataMocker is mocker class instance. To create custom data mocker extend OpenAPIServer\Mock\OpenApiDataMockerInterface.
• getMockResponseCallback is callback before mock data generation. Above example shows how to enable mock feature for only requests with {{X-OpenAPIServer}}-mock: ping HTTP header. Adjust requests filtering to fit your project requirements. This function must return single response schema from $responses array parameter. Mock feature is disabled when callback returns anything beside array.
• afterCallback is callback executed after mock data generation. Most obvious use case is append specific HTTP headers to distinguish real and fake responses. This function must always return response instance.

Supported features

All data types supported except specific string formats: email, uuid, password which are poorly implemented.

Data Types Support

Data Type	Data Format	Supported
integer	int32	✅
integer	int64	✅
number	float	✅
number	double
string	byte	✅
string	binary	✅
boolean		✅
string	date	✅
string	date-time	✅
string	password	✅
string	email	✅
string	uuid	✅

Data Options Support

Data Type	Option	Supported
string	minLength	✅
string	maxLength	✅
string	enum	✅
string	pattern
integer	minimum	✅
integer	maximum	✅
integer	exclusiveMinimum	✅
integer	exclusiveMaximum	✅
number	minimum	✅
number	maximum	✅
number	exclusiveMinimum	✅
number	exclusiveMaximum	✅
array	items	✅
array	additionalItems
array	minItems	✅
array	maxItems	✅
array	uniqueItems
object	properties	✅
object	maxProperties
object	minProperties
object	patternProperties
object	additionalProperties
object	required
*	$ref	✅
*	allOf
*	anyOf
*	oneOf
*	not

Known Limitations

Avoid circular refs in your schema. Schema below can cause infinite loop and Out of Memory PHP error:

# ModelA has reference to ModelB while ModelB has reference to ModelA.
# Mock server will produce huge nested JSON example and ended with `Out of Memory` error.
definitions:
  ModelA:
    type: object
    properties:
      model_b:
        $ref: '#/definitions/ModelB'
  ModelB:
    type: array
    items:
      $ref: '#/definitions/ModelA'

Don't ref scalar types, because generator will not produce models which mock server can find. So schema below will cause error:

# generated build contains only `OuterComposite` model class which referenced to not existed `OuterNumber`, `OuterString`, `OuterBoolean` classes
# mock server cannot mock `OuterComposite` model and throws exception
definitions:
  OuterComposite:
    type: object
    properties:
      my_number:
        $ref: '#/definitions/OuterNumber'
      my_string:
        $ref: '#/definitions/OuterString'
      my_boolean:
        $ref: '#/definitions/OuterBoolean'
  OuterNumber:
    type: number
  OuterString:
    type: string
  OuterBoolean:
    type: boolean