An app for getting general info and stats about the API edpoints and their 'examples' state.

Author: siamakp-elastic

src/scripts/examples-stats/EndpointInfoGenerator.py

@@ -0,0 +1,95 @@
+import os
+import re
+from typing import List
+from pathlib import Path
+from constants import EXAMPLES_FOLDER
+from dataclasses import dataclass, field
+
+@dataclass
+class EndpointInfo:
+    path: str = None
+    has_examples_subfolder: bool = False
+    num_request_examples: int = 0
+    num_response_examples: int = 0
+    num_examples: int = 0
+    examples_subfolders = []
+    recognized_examples_subfolders: set[str] = field(default_factory=set)
+    examples_response_codes: set[str] = field(default_factory=set)
+
+class EndpointInfoGenerator:
+    def __init__(self):
+        self.spec_path = "."
+
+    # Get all the folders in a path
+    def get_folders(self, path: str) -> List[Path]:
+        return [f for f in os.listdir(path) if os.path.isdir(os.path.join(path, f))]
+
+    def get_files(self, path: str) -> List[str]:
+        return [f for f in os.listdir(path) if os.path.isfile(os.path.join(path, f))]
+
+    def is_example_file(self, file: str) -> bool:
+        if file.endswith(".yaml"):
+            return True
+        print(f"WARNING: Found non-YAML example file: {file}")
+        return False
+
+    def get_example_files_in_folder(self, path: str) -> List[str]:
+        example_files = []
+        for file in self.get_files(path):
+            if self.is_example_file(file):
+                example_files.append(file)
+        return example_files
+
+    def get_request_subfolder(self, endpoint_path) -> str:
+        examples_path = os.path.join(endpoint_path, EXAMPLES_FOLDER)
+        request_examples_path = os.path.join(examples_path, "request")
+        if os.path.exists(request_examples_path):
+            return "request"
+        return None
+
+    def get_response_subfolders(self, endpoint_path) -> int:
+        examples_path = os.path.join(endpoint_path, EXAMPLES_FOLDER)
+        response_examples_folders = []
+        response_examples_path = os.path.join(examples_path, "response")
+        if os.path.exists(response_examples_path):
+            response_examples_folders.append("response")
+        else:
+            examples_subfolders = self.get_folders(examples_path)
+            for examples_subfolder in examples_subfolders:
+                # Look for folders of the pattern "nnn_response"
+                if re.match(r"[0-9]{3}_response", examples_subfolder):
+                    response_examples_folders.append(examples_subfolder)
+        return response_examples_folders
+
+    def get_response_code_from_response_folder(self, folder: str) -> str:
+        if folder == "response":
+            return "200"
+        match = re.match(r"(\d{3})_response", folder)
+        if match:
+            return match.group(1)
+        raise Exception(f"Invalid response folder: {folder}")
+
+    def get_endpoint_info(self, endpoint_path: str) -> EndpointInfo:
+        endpoint_path_relative_to_spec = os.path.relpath(endpoint_path, self.spec_path)
+        endpoint_info = EndpointInfo(path=endpoint_path_relative_to_spec)
+        # If there is no 'examples' folder, return EndpointInfo with
+        # default values
+        examples_path = os.path.join(endpoint_path, EXAMPLES_FOLDER)
+        if not os.path.exists(examples_path):
+            return endpoint_info
+        endpoint_info.examples_subfolders = self.get_folders(examples_path)
+        request_subfolder = self.get_request_subfolder(endpoint_path)
+        if request_subfolder:
+            endpoint_info.recognized_examples_subfolders.add(request_subfolder)
+            examples_request_path = os.path.join(examples_path, request_subfolder)
+            endpoint_info.num_request_examples = len(self.get_example_files_in_folder(examples_request_path))
+        response_subfolders = self.get_response_subfolders(endpoint_path)
+        if (len(response_subfolders) > 0):
+                endpoint_info.recognized_examples_subfolders.update(response_subfolders)
+                for response_subfolder in response_subfolders:
+                    response_code = self.get_response_code_from_response_folder(response_subfolder)
+                    endpoint_info.examples_response_codes.add(response_code)  
+                    examples_response_path = os.path.join(examples_path, response_subfolder)
+                    endpoint_info.num_response_examples += len(self.get_example_files_in_folder(examples_response_path))
+        endpoint_info.num_examples = endpoint_info.num_request_examples + endpoint_info.num_response_examples
+        return endpoint_info

src/scripts/examples-stats/EndpointPathsFinder.py

@@ -0,0 +1,45 @@
+import os
+from typing import List
+from pathlib import Path
+
+class EndpointPathsFinder:
+    def __init__(self):
+        self.spec_path = "."
+
+    def get_folders(self, path: str) -> List[Path]:
+        return [f for f in os.listdir(path) if os.path.isdir(os.path.join(path, f))]
+
+    def is_endpoint_group_folder(self, folder: str) -> bool:
+        # Other than _global, any folder starting with underscore is
+        # not an endpoint group folder
+        if folder == "_global":
+            return True
+        if folder.startswith("_"):
+            return False
+        return True
+
+    def get_endpoint_group_folders(self) -> List[Path]:  
+        folders = self.get_folders(self.spec_path)
+        return [f for f in folders if self.is_endpoint_group_folder(f)]
+
+    def is_endpoint_folder(self, folder: str) -> bool:
+        if folder == "_types":
+            return False
+        return True 
+
+    def get_endpoint_folders(self, path: str) -> List[Path]:
+        folders = self.get_folders(path)
+        return [f for f in folders if self.is_endpoint_folder(f)]
+
+    def get_endpoint_paths(self) -> List[str]:
+        endpoint_paths = []
+        group_folders = self.get_endpoint_group_folders()
+        for group_folder in group_folders:
+            group_path = os.path.join(self.spec_path, group_folder)
+            group_endpoint_folders = self.get_endpoint_folders(group_path)
+            for endpoint_folder in group_endpoint_folders:
+                endpoint_paths.append(os.path.join(group_path, endpoint_folder))
+        return endpoint_paths
+
+    def find_paths(self) -> List[str]:
+        return self.get_endpoint_paths()

src/scripts/examples-stats/ExamplesInfoGenerator.py

@@ -0,0 +1,31 @@
+from typing import List
+from dataclasses import dataclass   
+from EndpointPathsFinder import EndpointPathsFinder
+from EndpointInfoGenerator import EndpointInfo, EndpointInfoGenerator
+from ExamplesStatsGenerator import ExampleStats, ExamplesStatsGenerator
+
+@dataclass
+class ExamplesInfo:
+    endpoints_info: List[EndpointInfo]
+    stats: ExampleStats
+
+class ExamplesInfoGenerator:
+    def __init__(self):
+        self.endpoint_paths_finder = EndpointPathsFinder()
+        self.endpoint_info_processor = EndpointInfoGenerator()
+
+    def get_examples_info(self) -> ExamplesInfo:
+        endpoint_paths_finder = EndpointPathsFinder()
+        endpoint_paths = endpoint_paths_finder.find_paths()
+        endpoint_info_list = []
+        stats = ExampleStats()
+        for endpoint_path in endpoint_paths:
+            stats.num_endpoints += 1
+            endpoint_info = self.endpoint_info_processor.get_endpoint_info(endpoint_path)
+            endpoint_info_list.append(endpoint_info)
+
+        examples_stats_generator = ExamplesStatsGenerator(endpoint_info_list)   
+        stats = examples_stats_generator.get_stats()
+
+        examples_info = ExamplesInfo(endpoint_info_list, stats)
+        return examples_info

src/scripts/examples-stats/ExamplesStatsGenerator.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass
+from typing import List
+from EndpointInfoGenerator import EndpointInfo
+
+@dataclass
+class ExampleStats:
+    num_endpoints: int = 0
+    num_endpoints_with_examples: int = 0
+    num_endpoints_with_no_examples: int = 0
+    num_endpoints_with_only_request_examples: int = 0
+    num_endpoints_with_only_response_examples: int = 0
+    num_endpoints_with_both_request_and_response_examples: int = 0
+    num_endpoints_with_non_200_response_code_examples: int = 0
+    max_examples_per_endpoint: int = 0
+
+class ExamplesStatsGenerator:
+    def __init__(self, endpoint_info_list: List[EndpointInfo]):
+        self.endpoint_info_list = endpoint_info_list
+        self.spec_path = "."
+
+    def get_stats(self) -> ExampleStats: 
+        stats = ExampleStats()
+        for endpoint_info in self.endpoint_info_list:
+            stats.num_endpoints += 1
+
+            if endpoint_info.num_examples > 0:
+                stats.num_endpoints_with_examples += 1
+
+            if endpoint_info.num_examples > stats.max_examples_per_endpoint:
+                stats.max_examples_per_endpoint = endpoint_info.num_examples
+
+            if endpoint_info.num_request_examples > 0 and endpoint_info.num_response_examples == 0:
+                stats.num_endpoints_with_only_request_examples += 1
+            elif endpoint_info.num_request_examples == 0 and endpoint_info.num_response_examples > 0:
+                stats.num_endpoints_with_only_response_examples += 1
+            elif endpoint_info.num_request_examples > 0 and endpoint_info.num_response_examples > 0:
+                stats.num_endpoints_with_both_request_and_response_examples += 1
+            else:
+                stats.num_endpoints_with_no_examples += 1
+
+            non_200_response_codes = endpoint_info.examples_response_codes - {"200"}
+            if len(non_200_response_codes) > 0:
+                stats.num_endpoints_with_non_200_response_code_examples += 1
+        return stats

src/scripts/examples-stats/constants.py

@@ -0,0 +1,2 @@
+DEFAULT_SPEC_PATH = "../../../specification"
+EXAMPLES_FOLDER = "examples"

src/scripts/examples-stats/main.py

@@ -0,0 +1,53 @@
+#!/usr/bin/python3
+
+import os
+from constants import DEFAULT_SPEC_PATH
+from EndpointPathsFinder import EndpointPathsFinder
+from ExamplesInfoGenerator import ExamplesInfoGenerator, ExamplesInfo, ExampleStats
+
+def print_stats(stats: ExampleStats):
+    print ("===============")
+    print ("==== Stats ====")
+    print ("===============")
+    print(f"Number of endpoints: {stats.num_endpoints}")
+    print(f"Number of endpoints with no request or response examples: {stats.num_endpoints_with_no_examples}")
+    print(f"Number of endpoints with examples: {stats.num_endpoints_with_examples}")
+    print(f"    {stats.num_endpoints_with_only_request_examples:>4}: Only request examples")  
+    print(f"    {stats.num_endpoints_with_only_response_examples:>4}: Only response examples")
+    print(f"    {stats.num_endpoints_with_both_request_and_response_examples:>4}: Both request and response examples")
+    print(f"Number of endpoints with non-200 response code examples: {stats.num_endpoints_with_non_200_response_code_examples}")    
+    print(f"Max examples per endpoint: {stats.max_examples_per_endpoint}")
+    print ("===============\n")
+
+def main():
+    # Using a default spc path. We should add an option 
+    # for getting the spec path as a command line argument
+    os.chdir(DEFAULT_SPEC_PATH)
+    examples_info_generator = ExamplesInfoGenerator()
+    examples_info: ExamplesInfo = examples_info_generator.get_examples_info()
+    # === print stats
+    print_stats(examples_info.stats)
+    # === print paths with max examples
+    print("Paths with max examples:")
+    for endpoint_info in examples_info.endpoints_info:
+        if endpoint_info.num_examples == examples_info.stats.max_examples_per_endpoint:
+            print(f"    {endpoint_info.path} with {endpoint_info.num_examples} examples")
+    print()
+    # === print all recognized examples subfolders
+    all_examples_subfolders = set()
+    all_recognized_examples_subfolders = set()
+    for endpoint_info in examples_info.endpoints_info:
+        all_examples_subfolders.update(endpoint_info.examples_subfolders)
+        all_recognized_examples_subfolders.update(endpoint_info.recognized_examples_subfolders) 
+    print("All recognized subfolders of 'examples' folder:")
+    for folder in all_recognized_examples_subfolders:
+        print(f"    {folder}")
+    print()
+    # === print unrecognized examples subfolders
+    unrecognized_examples_subfolders = all_examples_subfolders - all_recognized_examples_subfolders
+    print("unrecognized subfolders of 'examples' folder:")    
+    for folder in unrecognized_examples_subfolders:
+        print(f"    {folder}")
+
+if __name__ == "__main__":
+    main()