• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

DerManoMann / openapi-verifier / 43971455476

12 Nov 2026 09:32PM UTC coverage: 93.711% (+0.1%) from 93.585%
43971455476

push

github

web-flow
feat(Recorder): record verified responses as examples for swagger-php (#97)

`ExampleRecorder` writes each body the verifier has validated to
`<method>/<path template>/<status>.json`, with JSON pointers scrubbed.
`OPENAPI_VERIFIER_EXAMPLES` and `OPENAPI_VERIFIER_EXAMPLES_SCRUB` turn it
on for every adapter. `Integrations\OpenApi\RecordedExamplesPlugin` adds
the recorded bodies to a swagger-php 7.3+ build as response examples.

50 of 53 new or added lines in 4 files covered. (94.34%)

298 of 318 relevant lines covered (93.71%)

27.62 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.15
/src/ExampleRecorder.php
1
<?php declare(strict_types=1);
2

3
namespace Radebatz\OpenApi\Verifier;
4

5
/**
6
 * Writes each verified response body to a directory, as an example for the document.
7
 *
8
 * A body is written to `<directory>/<method>/<path template>/<status>.json`, so
9
 * `GET /users/{id}` answered with 200 is `get/users/{id}/200.json`. One example per operation and
10
 * status: the last one recorded wins, so the files stay stable from one run to the next.
11
 *
12
 * Before writing, the value at each JSON pointer in `$scrub` is replaced with `$placeholder`. A
13
 * `*` segment matches every key or index, so `/items/*\/email` covers each item of a list.
14
 */
15
final class ExampleRecorder
16
{
17
    /** The directory to record into; recording is off when it is not set. */
18
    public const ENV_EXAMPLES = 'OPENAPI_VERIFIER_EXAMPLES';
19

20
    /** JSON pointers to scrub, separated by commas. */
21
    public const ENV_EXAMPLES_SCRUB = 'OPENAPI_VERIFIER_EXAMPLES_SCRUB';
22

23
    /**
24
     * @param list<string> $scrub JSON pointers whose values are replaced before writing
25
     */
26
    public function __construct(
27
        private readonly string $directory,
28
        private readonly array $scrub = [],
29
        private readonly mixed $placeholder = '***',
30
    ) {
31
    }
6 ✔
32

33
    /**
34
     * A recorder for the directory in `OPENAPI_VERIFIER_EXAMPLES`, or `null` when it is not set.
35
     */
36
    public static function fromEnvironment(): ?self
37
    {
38
        $directory = getenv(self::ENV_EXAMPLES);
83 ✔
39
        if (false === $directory || '' === $directory) {
83 ✔
40
            return null;
83 ✔
41
        }
42

43
        $scrub = array_values(array_filter(array_map(trim(...), explode(',', (string) getenv(self::ENV_EXAMPLES_SCRUB)))));
1 ✔
44

45
        return new self($directory, $scrub);
1 ✔
46
    }
47

48
    /**
49
     * The file holding the example for the given operation and status code.
50
     */
51
    public static function filename(string $directory, string $method, string $pathTemplate, int $statusCode): string
52
    {
53
        $path = trim($pathTemplate, '/');
6 ✔
54

55
        return rtrim($directory, '/') . '/' . strtolower($method) . ('' === $path ? '' : '/' . $path) . '/' . $statusCode . '.json';
6 ✔
56
    }
57

58
    public function record(string $method, string $pathTemplate, int $statusCode, mixed $data): void
59
    {
60
        foreach ($this->scrub as $pointer) {
6 ✔
61
            $data = $this->scrubbed($data, array_slice(explode('/', $pointer), 1));
2 ✔
62
        }
63

64
        $filename = self::filename($this->directory, $method, $pathTemplate, $statusCode);
6 ✔
65
        if (!is_dir($dir = dirname($filename)) && !mkdir($dir, 0o777, true) && !is_dir($dir)) {
6 ✔
NEW
66
            throw new \RuntimeException(sprintf('Cannot create the examples directory "%s"', $dir));
×
67
        }
68

69
        file_put_contents($filename, json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR) . "\n");
6 ✔
70
    }
71

72
    /**
73
     * @param list<string> $segments the pointer's segments, still escaped
74
     */
75
    private function scrubbed(mixed $data, array $segments): mixed
76
    {
77
        if ([] === $segments) {
2 ✔
78
            return $this->placeholder;
2 ✔
79
        }
80

81
        $segment = str_replace(['~1', '~0'], ['/', '~'], array_shift($segments));
2 ✔
82

83
        if ($data instanceof \stdClass) {
2 ✔
84
            foreach (get_object_vars($data) as $key => $value) {
2 ✔
85
                if ('*' === $segment || (string) $key === $segment) {
2 ✔
86
                    $data->{$key} = $this->scrubbed($value, $segments);
2 ✔
87
                }
88
            }
89
        } elseif (is_array($data)) {
1 ✔
90
            foreach ($data as $key => $value) {
1 ✔
91
                if ('*' === $segment || (string) $key === $segment) {
1 ✔
92
                    $data[$key] = $this->scrubbed($value, $segments);
1 ✔
93
                }
94
            }
95
        }
96

97
        return $data;
2 ✔
98
    }
99
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc