diff --git a/modules/custom/dkan_metastore/src/WebServiceApiDocs.php b/modules/custom/dkan_metastore/src/WebServiceApiDocs.php index b413b376e..7e4eaa0a9 100644 --- a/modules/custom/dkan_metastore/src/WebServiceApiDocs.php +++ b/modules/custom/dkan_metastore/src/WebServiceApiDocs.php @@ -75,29 +75,58 @@ public function __construct(Docs $docsController, Service $metastoreService) { */ public function getDatasetSpecific(string $identifier) { $fullSpec = $this->docsController->getJsonFromYmlFile(); - $spec = $this->keepDatasetSpecificEndpoints($fullSpec, $this->endpointsToKeep); - // Remove the security schemes. unset($spec['components']['securitySchemes']); - // Remove required parameters, since now part of path. - unset($spec['paths']['/api/1/datastore/sql']['get']['parameters']); - unset($spec['paths']['/api/1/metastore/schemas/dataset/items/{identifier}']['get']['parameters']); - // Keep only the tags needed, so remove the properties tag. - $spec['tags'] = [ - ["name" => "Dataset"], - ["name" => "SQL Query"], - ]; - // Replace the dataset uuid placeholder. + // Tags can be added later when needed, remove them for now. + $spec['tags'] = []; + + $spec = $this->modifyDatasetEndpoint($spec, $identifier); + $spec = $this->modifySqlEndpoint($spec, $identifier); + return $this->getResponse($spec); + } + + /** + * Modify the generic dataset endpoint to be specific to the current dataset. + * + * @param array $spec + * The original spec. + * @param string $identifier + * Dataset uuid. + * + * @return array + * Spec with dataset-specific metastore get endpoint. + */ + private function modifyDatasetEndpoint(array $spec, string $identifier) { if (isset($spec['paths']['/api/1/metastore/schemas/dataset/items/{identifier}'])) { + unset($spec['paths']['/api/1/metastore/schemas/dataset/items/{identifier}']['get']['parameters']); + // Replace the dataset uuid placeholder. $spec['paths']['/api/1/metastore/schemas/dataset/items/' . $identifier] = $spec['paths']['/api/1/metastore/schemas/dataset/items/{identifier}']; unset($spec['paths']['/api/1/metastore/schemas/dataset/items/{identifier}']); + // Keep only the tags needed, starting with the dataset tag. + $spec['tags'][] = ["name" => "Dataset"]; } + return $spec; + } - // Replace the sql endpoint query placeholder. - $spec = $this->replaceDistributions($spec, $identifier); - - return $this->getResponse($spec); + /** + * Modify the generic sql endpoint to be specific to the current dataset. + * + * @param array $spec + * The original spec. + * @param string $identifier + * Dataset uuid. + * + * @return array + * Spec with dataset-specific datastore sql endpoint. + */ + private function modifySqlEndpoint(array $spec, string $identifier) { + if (isset($spec['paths']['/api/1/datastore/sql'])) { + unset($spec['paths']['/api/1/datastore/sql']['get']['parameters']); + $spec = $this->replaceDistributions($spec, $identifier); + $spec['tags'][] = ["name" => "SQL Query"]; + } + return $spec; } /** diff --git a/modules/custom/dkan_metastore/tests/src/Unit/WebServiceApiDocsTest.php b/modules/custom/dkan_metastore/tests/src/Unit/WebServiceApiDocsTest.php index 60560c192..27f1c7888 100644 --- a/modules/custom/dkan_metastore/tests/src/Unit/WebServiceApiDocsTest.php +++ b/modules/custom/dkan_metastore/tests/src/Unit/WebServiceApiDocsTest.php @@ -22,21 +22,10 @@ class WebServiceApiDocsTest extends TestCase { public function testGetDatasetSpecific() { $mockChain = $this->getCommonMockChain(); - // Test against ./docs/dkan_api_openapi_spec.yml. - $endpointsToKeep = [ - // Target paths. - '/api/1/metastore/schemas/dataset/items/{identifier}' => ['get'], - '/api/1/datastore/sql' => ['get'], - // Non-existent operation. - '/api/1/some/other/path' => ['get'], - // Non-existent path. - 'api/1/non/existent/path' => ['put'], - ]; - $controller = WebServiceApiDocs::create($mockChain->getMock()); - $response = $controller->getDatasetSpecific(1, $endpointsToKeep); + $response = $controller->getDatasetSpecific(1); - $spec = '{"openapi":"3.0.1","info":{"title":"API Documentation","version":"Alpha"},"paths":{"\/api\/1\/metastore\/schemas\/dataset\/items\/1":{"get":{"summary":"Get this dataset","tags":["Dataset"],"responses":{"200":{"description":"Ok"}}}}},"tags":[{"name":"Dataset"},{"name":"SQL Query"}]}'; + $spec = '{"openapi":"3.0.1","info":{"title":"API Documentation","version":"Alpha"},"tags":[{"name":"Dataset"},{"name":"SQL Query"}],"paths":{"\/api\/1\/datastore\/sql":{"get":{"summary":"Query resources","tags":["SQL Query"],"responses":{"200":{"description":"Ok"}}}},"\/api\/1\/metastore\/schemas\/dataset\/items\/1":{"get":{"summary":"Get this dataset","tags":["Dataset"],"responses":{"200":{"description":"Ok"}}}}}}'; $this->assertEquals($spec, $response->getContent()); } @@ -46,6 +35,7 @@ public function testGetDatasetSpecific() { */ private function getCommonMockChain() { $serializer = new Yaml(); + // Test against ./docs/dkan_api_openapi_spec.yml. $yamlSpec = file_get_contents(__DIR__ . "/docs/dkan_api_openapi_spec.yml"); $mockChain = new Chain($this); diff --git a/modules/custom/dkan_metastore/tests/src/Unit/docs/dkan_api_openapi_spec.yml b/modules/custom/dkan_metastore/tests/src/Unit/docs/dkan_api_openapi_spec.yml index 04203d491..633a3e1cf 100644 --- a/modules/custom/dkan_metastore/tests/src/Unit/docs/dkan_api_openapi_spec.yml +++ b/modules/custom/dkan_metastore/tests/src/Unit/docs/dkan_api_openapi_spec.yml @@ -2,6 +2,10 @@ openapi: 3.0.1 info: title: API Documentation version: Alpha +tags: + - name: Dataset + - name: SQL Query + - name: Another Tag paths: /api/1/metastore/schemas/dataset/items/{identifier}: get: @@ -26,6 +30,16 @@ paths: description: Ok # Though an empty verb invalidates the spec, test its removal by dataset-specific docs. post: + /api/1/datastore/sql: + get: + summary: Query resources + tags: + - SQL Query + parameters: + - $ref: '#/components/parameters/query' + responses: + '200': + description: Ok /api/1/some/other/path: patch: summary: This path and operation should not be present in dataset-specific docs.