Skip to content

Commit d6b8fe8

Browse files
vearutopvearutop
authored
Add JSDoc types renderer from JSON Schema (#36)
1 parent df29f1b commit d6b8fe8

File tree

4 files changed

+321
-1
lines changed

4 files changed

+321
-1
lines changed

‎CHANGELOG.md

+6
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
44
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
55
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
66

7+
## [0.2.29] - 2021-04-07
8+
9+
### Added
10+
- JSDoc type builder from JSON Schema.
11+
712
## [0.2.28] - 2020-09-22
813

914
### Added
@@ -63,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
6368
### Fixed
6469
- Description trimming bug.
6570

71+
[0.2.29]: https://github.com/swaggest/php-code-builder/compare/v0.2.28...v0.2.29
6672
[0.2.28]: https://github.com/swaggest/php-code-builder/compare/v0.2.27...v0.2.28
6773
[0.2.27]: https://github.com/swaggest/php-code-builder/compare/v0.2.26...v0.2.27
6874
[0.2.26]: https://github.com/swaggest/php-code-builder/compare/v0.2.25...v0.2.26

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ test:
1414
@php -derror_reporting="E_ALL & ~E_DEPRECATED" vendor/bin/phpunit
1515

1616
test-coverage:
17-
@php -derror_reporting="E_ALL & ~E_DEPRECATED" -dzend_extension=xdebug.so vendor/bin/phpunit --coverage-text --coverage-clover=coverage.xml
17+
@php -derror_reporting="E_ALL & ~E_DEPRECATED" -dzend_extension=xdebug.so -dxdebug.mode=coverage vendor/bin/phpunit --coverage-text --coverage-clover=coverage.xml
1818

1919
gen:
2020
@php ./tools/generate_swagger_structures.php

‎src/JSDoc/TypeBuilder.php

+262
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
<?php
2+
3+
namespace Swaggest\PhpCodeBuilder\JSDoc;
4+
5+
use Swaggest\CodeBuilder\CodeBuilder;
6+
use Swaggest\JsonSchema\Schema;
7+
use Swaggest\PhpCodeBuilder\PhpCode;
8+
9+
class TypeBuilder
10+
{
11+
/** @var \SplObjectStorage */
12+
private $processed;
13+
14+
public $trimNamePrefix = [
15+
'#/definitions'
16+
];
17+
18+
public $file = '';
19+
20+
public function __construct()
21+
{
22+
$this->processed = new \SplObjectStorage();
23+
}
24+
25+
/**
26+
* @param Schema|boolean $schema
27+
* @param string $path
28+
* @return string
29+
*/
30+
public function getTypeString($schema, $path = '')
31+
{
32+
$schema = Schema::unboolSchema($schema);
33+
34+
$isOptional = false;
35+
$isObject = false;
36+
$isArray = false;
37+
$isBoolean = false;
38+
$isString = false;
39+
$isNumber = false;
40+
41+
$type = $schema->type;
42+
if (!is_array($type)) {
43+
$type = [$type];
44+
}
45+
46+
$or = [];
47+
48+
if ($schema->oneOf !== null) {
49+
foreach ($schema->oneOf as $item) {
50+
$or[] = $this->getTypeString($item);
51+
}
52+
}
53+
54+
if ($schema->anyOf !== null) {
55+
foreach ($schema->anyOf as $item) {
56+
$or[] = $this->getTypeString($item);
57+
}
58+
}
59+
60+
if ($schema->allOf !== null) {
61+
foreach ($schema->allOf as $item) {
62+
$or[] = $this->getTypeString($item);
63+
}
64+
}
65+
66+
if ($schema->then !== null) {
67+
$or[] = $this->getTypeString($schema->then);
68+
}
69+
70+
if ($schema->else !== null) {
71+
$or[] = $this->getTypeString($schema->else);
72+
}
73+
74+
foreach ($type as $i => $t) {
75+
switch ($t) {
76+
case Schema::NULL:
77+
$isOptional = true;
78+
break;
79+
80+
case Schema::OBJECT:
81+
$isObject = true;
82+
break;
83+
84+
case Schema::_ARRAY:
85+
$isArray = true;
86+
break;
87+
88+
case Schema::NUMBER:
89+
case Schema::INTEGER:
90+
$isNumber = true;
91+
break;
92+
93+
case Schema::STRING:
94+
$isString = true;
95+
break;
96+
97+
case Schema::BOOLEAN:
98+
$isBoolean = true;
99+
break;
100+
101+
}
102+
}
103+
104+
if ($isObject) {
105+
$typeAdded = false;
106+
107+
if (!empty($schema->properties)) {
108+
if ($this->processed->contains($schema)) {
109+
$or [] = $this->processed->offsetGet($schema);
110+
$typeAdded = true;
111+
} else {
112+
if ($schema instanceof Schema) {
113+
$typeName = $this->typeName($schema, $path);
114+
$this->makeObjectTypeDef($schema, $path);
115+
116+
$or [] = $typeName;
117+
$typeAdded = true;
118+
}
119+
}
120+
121+
}
122+
123+
if ($schema->additionalProperties instanceof Schema) {
124+
$typeName = $this->getTypeString($schema->additionalProperties, $path . '/additionalProperties');
125+
$or [] = "object<string, $typeName>";
126+
$typeAdded = true;
127+
}
128+
129+
if (!empty($schema->patternProperties)) {
130+
foreach ($schema->patternProperties as $pattern => $propertySchema) {
131+
if ($propertySchema instanceof Schema) {
132+
$typeName = $this->getTypeString($propertySchema, $path . '/patternProperties/' . $pattern);
133+
$or [] = $typeName;
134+
$typeAdded = true;
135+
}
136+
}
137+
}
138+
139+
if (!$typeAdded) {
140+
$or [] = 'object';
141+
}
142+
}
143+
144+
if ($isArray) {
145+
$typeAdded = false;
146+
147+
if ($schema->items instanceof Schema) {
148+
$typeName = $this->getTypeString($schema->items, $path . '/items');
149+
$or [] = "array<$typeName>";
150+
$typeAdded = true;
151+
}
152+
153+
if ($schema->additionalItems instanceof Schema) {
154+
$typeName = $this->getTypeString($schema->additionalItems, $path . '/additionalItems');
155+
$or [] = "array<$typeName>";
156+
$typeAdded = true;
157+
}
158+
159+
if (!$typeAdded) {
160+
$or [] = 'array';
161+
}
162+
}
163+
164+
if ($isString) {
165+
$or [] = 'string';
166+
}
167+
168+
if ($isNumber) {
169+
$or [] = 'number';
170+
}
171+
172+
if ($isBoolean) {
173+
$or [] = 'boolean';
174+
}
175+
176+
$res = '';
177+
foreach ($or as $item) {
178+
if (!empty($item) && $item !== '*') {
179+
$res .= '|' . $item;
180+
}
181+
}
182+
183+
if ($res !== '') {
184+
$res = substr($res, 1);
185+
} else {
186+
$res = '*';
187+
}
188+
189+
return $res;
190+
}
191+
192+
private function typeName(Schema $schema, $path)
193+
{
194+
if ($fromRefs = $schema->getFromRefs()) {
195+
$path = $fromRefs[count($fromRefs) - 1];
196+
}
197+
198+
foreach ($this->trimNamePrefix as $prefix) {
199+
if ($prefix === substr($path, 0, strlen($prefix))) {
200+
$path = substr($path, strlen($prefix));
201+
}
202+
}
203+
204+
return PhpCode::makePhpName($path, false);
205+
}
206+
207+
private function makeObjectTypeDef(Schema $schema, $path)
208+
{
209+
$typeName = $this->typeName($schema, $path);
210+
$this->processed->attach($schema, $typeName);
211+
212+
$head = '';
213+
if (!empty($schema->title)) {
214+
$head .= $schema->title . "\n";
215+
}
216+
217+
if (!empty($schema->description)) {
218+
$head .= $schema->description . "\n";
219+
}
220+
221+
if ($head !== '') {
222+
$head = "\n" . CodeBuilder::padLines(' * ', trim($head), false);
223+
}
224+
225+
$res = <<<JSDOC
226+
/**$head
227+
* @typedef {$typeName}
228+
* @type {object}
229+
230+
JSDOC;
231+
if (!empty($schema->properties)) {
232+
foreach ($schema->properties as $propertyName => $propertySchema) {
233+
$typeString = $this->getTypeString($propertySchema, $path . '/' . $propertyName);
234+
$res .= <<<JSDOC
235+
* @property {{$typeString}} {$propertyName}{$this->description($propertySchema)}.
236+
237+
JSDOC;
238+
239+
}
240+
}
241+
242+
$res .= <<<JSDOC
243+
*/
244+
245+
246+
JSDOC;
247+
248+
$this->file .= $res;
249+
250+
return $typeName;
251+
}
252+
253+
private function description(Schema $schema)
254+
{
255+
$res = str_replace("\n", " ", $schema->title . $schema->description);
256+
if ($res) {
257+
return ' - ' . rtrim($res, '.');
258+
}
259+
260+
return '';
261+
}
262+
}

‎tests/src/PHPUnit/JSDoc/JSDocTest.php

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<?php
2+
3+
namespace Swaggest\PhpCodeBuilder\Tests\PHPUnit\JSDoc;
4+
5+
use Swaggest\JsonSchema\Schema;
6+
use Swaggest\PhpCodeBuilder\JSDoc\TypeBuilder;
7+
8+
class JSDocTest extends \PHPUnit_Framework_TestCase
9+
{
10+
public function testJsonSchema()
11+
{
12+
$schemaData = <<<'JSON'
13+
{
14+
"$ref": "#/definitions/Person",
15+
"definitions": {
16+
"Person": {
17+
"type": "object",
18+
"properties": {
19+
"name": {"type": "string", "description": "Person name."},
20+
"age": {"type": "integer"},
21+
"isMale": {"type": "boolean"},
22+
"partner": {"$ref": "#/definitions/Person"},
23+
"children": {"type":"array", "items": {"$ref":"#/definitions/Person"}}
24+
}
25+
}
26+
}
27+
}
28+
JSON;
29+
$schema = Schema::import(json_decode($schemaData));
30+
$this->assertNotEmpty($schema);
31+
32+
$tb = new TypeBuilder();
33+
34+
$typeString = $tb->getTypeString($schema);
35+
$this->assertSame('Person', $typeString);
36+
$this->assertSame(<<<'JS'
37+
/**
38+
* @typedef Person
39+
* @type {object}
40+
* @property {string} name - Person name.
41+
* @property {number} age.
42+
* @property {boolean} isMale.
43+
* @property {Person} partner.
44+
* @property {array<Person>} children.
45+
*/
46+
47+
48+
JS
49+
, $tb->file);
50+
}
51+
52+
}

0 commit comments

Comments
 (0)