Created by: ybelenko
PR checklist
-
Read the contribution guidelines. -
If contributing template-only or documentation-only changes which will change sample output, build the project before. -
Run the shell script(s) under ./bin/
(or Windows batch scripts under.\bin\windows
) to update Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit, and these must match the expectations made by your contribution. You only need to run./bin/{LANG}-petstore.sh
,./bin/openapi3/{LANG}-petstore.sh
if updating the code or mustache templates for a language ({LANG}
) (e.g. php, ruby, python, etc). -
File the PR against the correct branch: master
,4.3.x
,5.0.x
. Default:master
. -
Copy the technical committee to review the pull request if your PR is targeting a particular programming language.
Closes #3545 (closed)
cc @jebentier, @dkarlovi, @mandrean, @jfastnacht, @ackintosh, @renepardon
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 extendOpenAPIServer\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