From 237973bcb96a9a6716a78db25d2747a09ff7d3be Mon Sep 17 00:00:00 2001 From: Eldad Fux Date: Tue, 26 Jan 2021 13:54:06 +0200 Subject: [PATCH] Added service descriptions to Swagger and OpenAPI3 specs --- app/config/services.php | 30 ++++++++++++++++++- app/controllers/web/home.php | 19 ++++++++++-- src/Appwrite/Specification/Format.php | 9 +++++- .../Specification/Format/OpenAPI3.php | 1 + .../Specification/Format/Swagger2.php | 1 + 5 files changed, 56 insertions(+), 4 deletions(-) diff --git a/app/config/services.php b/app/config/services.php index e500f9a24..90a452cfc 100644 --- a/app/config/services.php +++ b/app/config/services.php @@ -2,98 +2,126 @@ return [ '/' => [ + 'key' => 'homepage', 'name' => 'Homepage', 'controller' => 'web/home.php', 'sdk' => false, + 'docs' => false, 'tests' => false, ], 'console/' => [ + 'key' => 'console', 'name' => 'Console', 'controller' => 'web/console.php', 'sdk' => false, + 'docs' => false, 'tests' => false, ], 'v1/account' => [ + 'key' => 'account', 'name' => 'Account', 'description' => '/docs/services/account.md', 'controller' => 'api/account.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/avatars' => [ + 'key' => 'avatars', 'name' => 'Avatars', 'description' => '/docs/services/avatars.md', 'controller' => 'api/avatars.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/database' => [ + 'key' => 'database', 'name' => 'Database', 'description' => '/docs/services/database.md', 'controller' => 'api/database.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/locale' => [ + 'key' => 'locale', 'name' => 'Locale', 'description' => '/docs/services/locale.md', 'controller' => 'api/locale.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/health' => [ + 'key' => 'health', 'name' => 'Health', 'description' => '/docs/services/health.md', 'controller' => 'api/health.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/projects' => [ + 'key' => 'projects', 'name' => 'Projects', 'controller' => 'api/projects.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/storage' => [ + 'key' => 'storage', 'name' => 'Storage', 'description' => '/docs/services/storage.md', 'controller' => 'api/storage.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/teams' => [ + 'key' => 'teams', 'name' => 'Teams', 'description' => '/docs/services/teams.md', 'controller' => 'api/teams.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/users' => [ + 'key' => 'users', 'name' => 'Users', 'description' => '/docs/services/users.md', 'controller' => 'api/users.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/functions' => [ - 'name' => 'Users', + 'key' => 'functions', + 'name' => 'Functions', 'description' => '/docs/services/functions.md', 'controller' => 'api/functions.php', 'sdk' => true, + 'docs' => true, 'tests' => false, ], 'v1/mock' => [ + 'key' => 'mock', 'name' => 'Mock', 'description' => '', 'controller' => 'mock.php', 'sdk' => false, + 'docs' => false, 'tests' => true, ], 'v1/graphql' => [ + 'key' => 'graphql', 'name' => 'GraphQL', 'description' => 'GraphQL Endpoint', 'controller' => 'api/graphql.php', 'sdk' => false, + 'docs' => false, 'tests' => false, ], ]; diff --git a/app/controllers/web/home.php b/app/controllers/web/home.php index 8dc976986..c4cb6de31 100644 --- a/app/controllers/web/home.php +++ b/app/controllers/web/home.php @@ -216,6 +216,7 @@ App::get('/specs/:format') $routes = []; $models = []; + $services = []; $keys = [ APP_PLATFORM_CLIENT => [ @@ -317,6 +318,20 @@ App::get('/specs/:format') } } + foreach (Config::getParam('services', []) as $key => $service) { + if(!isset($service['docs']) // Skip service if not part of the public API + || !isset($service['sdk']) + || !$service['docs'] + || !$service['sdk']) { + continue; + } + + $services[] = [ + 'name' => $service['key'] ?? '', + 'description' => (!empty($service['description'])) ? file_get_contents(realpath(__DIR__.'/../../..'.$service['description'])) : '', + ]; + } + $models = $response->getModels(); foreach ($models as $key => $value) { @@ -327,11 +342,11 @@ App::get('/specs/:format') switch ($format) { case 'swagger2': - $format = new Swagger2($utopia, $routes, $models, $keys[$platform], $security[$platform]); + $format = new Swagger2($utopia, $services, $routes, $models, $keys[$platform], $security[$platform]); break; case 'open-api3': - $format = new OpenAPI3($utopia, $routes, $models, $keys[$platform], $security[$platform]); + $format = new OpenAPI3($utopia, $services, $routes, $models, $keys[$platform], $security[$platform]); break; default: diff --git a/src/Appwrite/Specification/Format.php b/src/Appwrite/Specification/Format.php index 6f2d154e4..cfe2a34a0 100644 --- a/src/Appwrite/Specification/Format.php +++ b/src/Appwrite/Specification/Format.php @@ -13,6 +13,11 @@ abstract class Format */ protected $app; + /** + * @var array + */ + protected $services; + /** * @var Route[] */ @@ -53,14 +58,16 @@ abstract class Format /** * @param App $app + * @param array $services * @param Route[] $routes * @param Model[] $models * @param array $keys * @param array $security */ - public function __construct(App $app, array $routes, array $models, array $keys, array $security) + public function __construct(App $app, array $services, array $routes, array $models, array $keys, array $security) { $this->app = $app; + $this->services = $services; $this->routes = $routes; $this->models = $models; $this->keys = $keys; diff --git a/src/Appwrite/Specification/Format/OpenAPI3.php b/src/Appwrite/Specification/Format/OpenAPI3.php index 117c7c93b..95ddf333f 100644 --- a/src/Appwrite/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/Specification/Format/OpenAPI3.php @@ -56,6 +56,7 @@ class OpenAPI3 extends Format ], ], 'paths' => [], + 'tags' => $this->services, 'components' => [ 'schemas' => [], 'securitySchemes' => $this->keys, diff --git a/src/Appwrite/Specification/Format/Swagger2.php b/src/Appwrite/Specification/Format/Swagger2.php index fbe8ded4e..7d4f5407f 100644 --- a/src/Appwrite/Specification/Format/Swagger2.php +++ b/src/Appwrite/Specification/Format/Swagger2.php @@ -57,6 +57,7 @@ class Swagger2 extends Format 'produces' => ['application/json'], 'securityDefinitions' => $this->keys, 'paths' => [], + 'tags' => $this->services, 'definitions' => [], 'externalDocs' => [ 'description' => $this->getParam('docs.description'),