diff options
| -rw-r--r-- | inc/Remote/Api.php | 3 | ||||
| -rw-r--r-- | inc/Remote/OpenApiDoc/OpenAPIGenerator.php (renamed from inc/Remote/OpenAPIGenerator.php) | 79 | ||||
| -rw-r--r-- | lib/exe/openapi.php | 2 |
3 files changed, 67 insertions, 17 deletions
diff --git a/inc/Remote/Api.php b/inc/Remote/Api.php index 65125e32c..d258d59b4 100644 --- a/inc/Remote/Api.php +++ b/inc/Remote/Api.php @@ -58,7 +58,6 @@ class Api * Get all available methods with remote access. * * @return ApiCall[] with information to all available methods - * @throws RemoteException */ public function getMethods() { @@ -76,7 +75,7 @@ class Api { if (!$this->coreMethods) { if ($apiCore === null) { - $this->coreMethods = (new ApiCore($this))->getMethods(); + $this->coreMethods = (new ApiCore())->getMethods(); } else { $this->coreMethods = $apiCore->getMethods(); } diff --git a/inc/Remote/OpenAPIGenerator.php b/inc/Remote/OpenApiDoc/OpenAPIGenerator.php index 54d81e659..c61ce0bb8 100644 --- a/inc/Remote/OpenAPIGenerator.php +++ b/inc/Remote/OpenApiDoc/OpenAPIGenerator.php @@ -1,23 +1,42 @@ <?php +namespace dokuwiki\Remote\OpenApiDoc; -namespace dokuwiki\Remote; - -use dokuwiki\Remote\OpenApiDoc\DocBlockClass; -use dokuwiki\Remote\OpenApiDoc\Type; +use dokuwiki\Remote\Api; +use dokuwiki\Remote\ApiCall; +use dokuwiki\Remote\ApiCore; use dokuwiki\Utf8\PhpString; +use ReflectionClass; +use ReflectionException; +use stdClass; +/** + * Generates the OpenAPI documentation for the DokuWiki API + */ class OpenAPIGenerator { - + /** @var Api */ protected $api; + /** @var array Holds the documentation tree while building */ protected $documentation = []; + /** + * OpenAPIGenerator constructor. + */ public function __construct() { $this->api = new Api(); + } + /** + * Generate the OpenAPI documentation + * + * @return string JSON encoded OpenAPI specification + */ + public function generate() + { + $this->documentation = []; $this->documentation['openapi'] = '3.1.0'; $this->documentation['info'] = [ 'title' => 'DokuWiki API', @@ -25,10 +44,6 @@ class OpenAPIGenerator 'version' => ((string)ApiCore::API_VERSION), ]; - } - - public function generate() - { $this->addServers(); $this->addSecurity(); $this->addMethods(); @@ -36,6 +51,11 @@ class OpenAPIGenerator return json_encode($this->documentation, JSON_PRETTY_PRINT); } + /** + * Add the current DokuWiki instance as a server + * + * @return void + */ protected function addServers() { $this->documentation['servers'] = [ @@ -45,6 +65,11 @@ class OpenAPIGenerator ]; } + /** + * Define the default security schemes + * + * @return void + */ protected function addSecurity() { $this->documentation['components']['securitySchemes'] = [ @@ -68,6 +93,11 @@ class OpenAPIGenerator ]; } + /** + * Add all methods available in the API to the documentation + * + * @return void + */ protected function addMethods() { $methods = $this->api->getMethods(); @@ -80,6 +110,13 @@ class OpenAPIGenerator } } + /** + * Create the schema definition for a single API method + * + * @param string $method API method name + * @param ApiCall $call The call definition + * @return array + */ protected function getMethodDefinition(string $method, ApiCall $call) { $description = $call->getDescription(); @@ -146,7 +183,7 @@ class OpenAPIGenerator if ($call->isPublic()) { $definition['security'] = [ - new \stdClass(), + new stdClass(), ]; $definition['description'] = 'This method is public and does not require authentication. ' . "\n\n" . $definition['description']; @@ -154,13 +191,20 @@ class OpenAPIGenerator if ($call->getDocs()->getTag('deprecated')) { $definition['deprecated'] = true; - $definition['description'] = '**This method is deprecated.** ' . $call->getDocs()->getTag('deprecated')[0] . + $definition['description'] = '**This method is deprecated.** ' . + $call->getDocs()->getTag('deprecated')[0] . "\n\n" . $definition['description']; } return $definition; } + /** + * Create the schema definition for the arguments of a single API method + * + * @param array $args The arguments of the method as returned by ApiCall::getArgs() + * @return array + */ protected function getMethodArguments($args) { if (!$args) { @@ -201,6 +245,13 @@ class OpenAPIGenerator return $schema; } + /** + * Generate an example value for the given parameter + * + * @param string $name The parameter's name + * @param string $type The parameter's type + * @return mixed + */ protected function generateExample($name, $type) { switch ($type) { @@ -218,7 +269,7 @@ class OpenAPIGenerator case 'array': return ['some-' . $name, 'other-' . $name]; default: - return new \stdClass(); + return new stdClass(); } } @@ -265,7 +316,7 @@ class OpenAPIGenerator if ($schema['type'] === 'object') { try { $baseType = $type->getBaseType(); - $doc = new DocBlockClass(new \ReflectionClass($baseType)); + $doc = new DocBlockClass(new ReflectionClass($baseType)); $schema['properties'] = []; foreach ($doc->getPropertyDocs() as $property => $propertyDoc) { $schema['properties'][$property] = array_merge( @@ -275,7 +326,7 @@ class OpenAPIGenerator $this->typeToSchema($propertyDoc->getType()) ); } - } catch (\ReflectionException $e) { + } catch (ReflectionException $e) { // The class is not available, so we cannot generate a schema } } diff --git a/lib/exe/openapi.php b/lib/exe/openapi.php index db12bf589..5eb7eaebd 100644 --- a/lib/exe/openapi.php +++ b/lib/exe/openapi.php @@ -7,7 +7,7 @@ global $INPUT; if ($INPUT->has('spec')) { header('Content-Type: application/json'); - $apigen = new \dokuwiki\Remote\OpenAPIGenerator(); + $apigen = new \dokuwiki\Remote\OpenApiDoc\OpenAPIGenerator(); echo $apigen->generate(); exit(); } |