introduce rich for nicer cli

Author: tkfoss

README.md

@@ -33,30 +33,48 @@ python -m build
 pip install dist/serverless_openapi_generator-1.0.0-py3-none-any.whl
 ```
 
-or run as `uv` tool:
+### CLI
+
+The tool now uses a sub-command structure for different stages of the generation process.
+
+#### 1. `generate-schemas`
+
+Generates JSON schemas from your Pydantic models.
 
 ```bash
-uvx --from git+https://github.com/tkfoss/python-serverless-openapi-documentation.git openapi-gen path/to/your/serverless.yml openapi.json
+openapi-gen generate-schemas --pydantic-source path/to/your/pydantic/models --output-dir path/to/your/schemas
 ```
 
-For more information on running tools with `uv`, see the [official documentation](https://docs.astral.sh/uv/guides/tools/#running-tools).
+**Arguments:**
+*   `--pydantic-source`: (Required) Path to the Pydantic models source directory.
+*   `--output-dir`: (Required) Directory to save the generated JSON schemas.
+
+#### 2. `generate-serverless`
+
+Generates a `serverless.yml` file from the JSON schemas and your project's metadata.
 
-**CLI:**
 ```bash
-openapi-gen openapi.json --serverless-yml-path path/to/your/serverless.yml
+openapi-gen generate-serverless --schema-dir path/to/your/schemas --project-dir path/to/your/project
 ```
 
-**Options:**
+**Arguments:**
+*   `--schema-dir`: (Required) Directory containing the JSON schemas generated in the previous step.
+*   `--project-dir`: (Optional) Path to the project root directory. This is used to find `pyproject.toml` for project metadata. If not provided, it's inferred from the schema directory.
 
-```
-output_file_path         Path to the output OpenAPI JSON file. (Required)
---serverless-yml-path    Path to the serverless.yml file. (Required if --pydantic-source is not used)
---openApiVersion         The OpenAPI version to generate for. Default: 3.0.3
---pre-hook               Path to a Python script to run before generation.
---pydantic-source        Path to the Pydantic models source directory.
---validate               Validate the generated OpenAPI spec.
+#### 3. `generate-spec`
+
+Generates the final OpenAPI specification from a `serverless.yml` file.
+
+```bash
+openapi-gen generate-spec openapi.json --serverless-yml-path path/to/your/serverless.yml
 ```
 
+**Arguments:**
+*   `output_file_path`: (Required) Path to the output OpenAPI JSON file.
+*   `--serverless-yml-path`: (Required) Path to the `serverless.yml` file.
+*   `--openApiVersion`: The OpenAPI version to generate for. Default: `3.0.3`.
+*   `--validate`: Validate the generated OpenAPI spec.
+
 ### Validation
 
 This tool also includes a script to validate an OpenAPI specification file against the OpenAPI 3.0.3 specification.
@@ -66,10 +84,7 @@ This tool also includes a script to validate an OpenAPI specification file again
 openapi-validate path/to/your/openapi.json
 ```
 
-You can also use the `--validate` flag with the `openapi-gen` command to automatically validate the generated spec:
-```bash
-openapi-gen path/to/your/serverless.yml openapi.json --validate
-```
+You can also use the `--validate` flag with the `generate-spec` command to automatically validate the generated spec.
 
 ### Configuration
 
@@ -133,49 +148,19 @@ The documentation format for functions, models, security schemes, and other prop
 *   **Private Endpoints**: Automatically applies an `x-api-key` security scheme for functions marked with `private: true`.
 *   **Inferred Request Bodies**: Generates `requestBody` documentation from a function's `request.schemas` configuration.
 *   **Specification Extensions**: Supports custom `x-` fields in most sections of the documentation.
-*   **Pre-processing Hooks**: Allows running a custom Python script to generate schemas or configurations before the main tool runs.
+*   **Automatic Tagging**: If no tags are provided for an API operation, a tag is automatically generated from the function's handler path. For example, a handler at `src.api.users.handler` will be tagged with `users`. This helps in organizing the generated documentation.
 
-### Pydantic Schema Generation
+### Pydantic-based Workflow
 
-This tool can automatically generate JSON schemas from your Pydantic models and create a complete OpenAPI specification, even if your project does not use the Serverless Framework. To use this feature, provide the path to your Pydantic models' source directory using the `--pydantic-source` argument. The tool will generate a serverless configuration in memory to facilitate the OpenAPI generation process.
+This tool can automatically generate JSON schemas from your Pydantic models and create a complete OpenAPI specification. This is particularly useful for projects that do not use the Serverless Framework.
 
-The tool will search for `dtos.py` files within the specified directory, generate JSON schemas for all Pydantic models found, and place them in an `openapi_models` directory at the root of your project. It will also extract project metadata from your `pyproject.toml` file to populate the `info` section of the OpenAPI document.
+The workflow is as follows:
 
-> **Note:** For the Pydantic schema generation to work correctly, the Python environment where you run `openapi-gen` must have all the dependencies of your project installed. This is because the tool needs to import your Pydantic models to generate the schemas. You can typically install your project's dependencies using a command like `pip install -r requirements.txt` or `poetry install`.
+1.  **Generate Schemas:** Use the `generate-schemas` command to create JSON schemas from your Pydantic models.
+2.  **Generate `serverless.yml`:** Use the `generate-serverless` command to create a `serverless.yml` file. This command uses the schemas from the previous step and project metadata from your `pyproject.toml` file.
+3.  **Generate OpenAPI Spec:** Use the `generate-spec` command with the newly created `serverless.yml` to generate the final `openapi.json`.
 
-**To Run with Pydantic:**
-```bash
-openapi-gen openapi.json --pydantic-source path/to/your/pydantic/models
-```
-
-### Pre-processing Hooks
-
-You can use the `--pre-hook` argument to specify a Python script that will be executed before the OpenAPI generation begins. This is useful for programmatically generating parts of your `serverless.yml` or the schema files it references.
-
-For example, you could have a script that generates JSON schemas from Pydantic models:
-
-**`generate_schemas.py`:**
-```python
-# A simplified example to generate schemas from Pydantic models
-import json
-from pydantic import BaseModel
-
-class MyModel(BaseModel):
-    id: int
-    name: str
-
-if __name__ == "__main__":
-    schema = MyModel.model_json_schema()
-    with open("models/MyModel.json", "w") as f:
-        json.dump(schema, f, indent=2)
-    print("Generated schema for MyModel.")
-```
-
-You would then run the tool like this:
-```bash
-openapi-gen openapi.json --serverless-yml-path serverless.yml --pre-hook generate_schemas.py
-```
-The `openapi-gen` tool will first execute `generate_schemas.py`, which creates the `models/MyModel.json` file. Then, when the generator processes your `serverless.yml`, it can reference that newly created schema via `${file(models/MyModel.json)}`.
+> **Note:** For the Pydantic schema generation to work correctly, the Python environment where you run `openapi-gen` must have all the dependencies of your project installed. This is because the tool needs to import your Pydantic models to generate the schemas.
 
 ## License
 

pyproject.toml

@@ -23,6 +23,7 @@ dependencies = [
     "jsonschema-spec",
     "openapi-spec-validator",
     "pydantic>=2.10.6",
+    "rich>=14.0.0",
 ]
 
 [tool.setuptools.packages.find]

src/serverless_openapi_generator/openapi_generator.py

@@ -3,8 +3,8 @@
 import yaml
 import os
 import re
-import subprocess
 from pathlib import Path
+from rich import print as rprint
 from . import owasp
 from .schema_handler import SchemaHandler
 from . import pydantic_handler
@@ -41,7 +41,7 @@ def _resolve_file_references(self, value):
                         else:
                             return yaml.safe_load(f)
                 except (IOError, yaml.YAMLError, json.JSONDecodeError) as e:
-                    print(f"Warning: Could not read or parse file reference {abs_path}: {e}")
+                    rprint(f"[yellow]Warning: Could not read or parse file reference {abs_path}: {e}[/yellow]")
                     return value
         return value
 
@@ -164,12 +164,21 @@ def create_operation_object(self, documentation, func, http_event):
         func_name = func['name']
         operation_id = f"{service_name}-{stage}-{func_name}"
 
+        tags = documentation.get('tags', [])
+        if not tags:
+            handler_path = func.get('details', {}).get('handler', '')
+            if handler_path:
+                # e.g. src.api.users.handler -> users
+                parts = handler_path.split('.')
+                if len(parts) > 2:
+                    tags.append(parts[-2])
+        
         obj = {
             'summary': documentation.get('summary', ''),
             'description': documentation.get('description', func['details'].get('description', '')),
             'operationId': operation_id,
             'parameters': [],
-            'tags': documentation.get('tags', []),
+            'tags': tags,
         }
 
         if documentation.get('pathParams'):
@@ -291,8 +300,6 @@ def create_media_type_object(self, models):
         content = {}
         if models:
             for media_type, schema_name in models.items():
-                print(f"Schema name: {schema_name}")
-                print(f"Models: {self.schema_handler.models}")
                 model_info = next((model for model in self.schema_handler.models if model['name'] == schema_name), None)
                 if model_info:
                     schema_ref = self.schema_handler.create_schema(schema_name, model_info.get('schema'))
@@ -402,77 +409,94 @@ def create_response_headers(self, headers_doc):
                 headers[header_name] = header_obj
         return headers
 
-def main():
-    parser = argparse.ArgumentParser(description='Generate OpenAPI v3 documentation from a serverless.yml file.')
-    parser.add_argument('output_file_path', type=str, help='Path to the output OpenAPI JSON file')
-    parser.add_argument('--serverless-yml-path', type=str, help='Path to the serverless.yml file. Required if --pydantic-source is not used.')
-    parser.add_argument('--openApiVersion', type=str, default='3.0.3', help='OpenAPI version to use')
-    parser.add_argument('--pre-hook', type=str, help='Path to a Python script to run before generation')
-    parser.add_argument('--pydantic-source', type=str, help='Path to the Pydantic models source directory')
-    parser.add_argument('--validate', action='store_true', help='Validate the generated OpenAPI spec')
-    args = parser.parse_args()
-
-    if not args.serverless_yml_path and not args.pydantic_source:
-        parser.error("Either --serverless-yml-path or --pydantic-source must be provided.")
-
-    # Execute the pre-hook script if provided
-    if args.pre_hook:
-        print(f"--- Running pre-hook script: {args.pre_hook} ---")
-        try:
-            subprocess.run(['python', args.pre_hook], check=True, text=True)
-            print("--- Pre-hook script finished successfully ---")
-        except FileNotFoundError:
-            print(f"Error: Pre-hook script not found at {args.pre_hook}")
-            return
-        except subprocess.CalledProcessError as e:
-            print(f"Error executing pre-hook script: {e}")
-            return
-
-    # Execute the Pydantic schema generation if the source is provided
-    if args.pydantic_source:
-        print(f"--- Running Pydantic schema generation from: {args.pydantic_source} ---")
-        project_root = Path(args.pydantic_source)
-        output_dir = project_root / "openapi_models"
-        
-        generated_schemas = pydantic_handler.generate_dto_schemas(project_root, output_dir, project_root)
-        project_meta = pydantic_handler.load_project_meta(project_root)
-        
-        serverless_config = pydantic_handler.generate_serverless_config(generated_schemas, project_meta, project_root)
-        
-        # Use a virtual file path in the project root for correct base directory resolution
-        effective_sls_path = project_root / "serverless.yml"
-        
-        print("--- Pydantic schema generation finished successfully ---")
-    else:
-        try:
-            with open(args.serverless_yml_path, 'r') as f:
-                serverless_config = yaml.safe_load(f)
-            effective_sls_path = args.serverless_yml_path
-        except FileNotFoundError:
-            print(f"Error: The file {args.serverless_yml_path} was not found.")
-            return
-        except yaml.YAMLError as e:
-            print(f"Error parsing YAML file: {e}")
-            return
+def generate_schemas(args):
+    rprint(f"[bold]--- Running Pydantic schema generation from: {args.pydantic_source} ---[/bold]")
+    project_root = Path(args.pydantic_source)
+    output_dir = Path(args.output_dir)
+    
+    pydantic_handler.generate_dto_schemas(project_root, output_dir, project_root)
+    rprint(f"[bold green]--- Pydantic schema generation finished successfully. Schemas are in {args.output_dir} ---[/bold green]")
+
+def generate_serverless(args):
+    rprint(f"[bold]--- Generating serverless.yml from schemas in {args.schema_dir} ---[/bold]")
+    schema_dir = Path(args.schema_dir)
+    project_root = Path(args.project_dir) if args.project_dir else schema_dir.parent
+
+    schemas = []
+    for file_path in schema_dir.glob("*.json"):
+        with open(file_path, 'r') as f:
+            schema = json.load(f)
+            schemas.append({
+                "name": file_path.stem,
+                "schema": schema
+            })
+
+    project_meta = pydantic_handler.load_project_meta(project_root)
+    serverless_config = pydantic_handler.generate_serverless_config(schemas, project_meta, project_root)
+    
+    output_path = project_root / "serverless.yml"
+    with open(output_path, 'w') as f:
+        yaml.dump(serverless_config, f)
+    
+    rprint(f"[bold green]--- serverless.yml generated at {output_path} ---[/bold green]")
+
+def generate_spec(args):
+    try:
+        with open(args.serverless_yml_path, 'r') as f:
+            serverless_config = yaml.safe_load(f)
+        effective_sls_path = args.serverless_yml_path
+    except FileNotFoundError:
+        rprint(f"[red]Error: The file {args.serverless_yml_path} was not found.[/red]")
+        return
+    except yaml.YAMLError as e:
+        rprint(f"[red]Error parsing YAML file: {e}[/red]")
+        return
 
     generator = DefinitionGenerator(serverless_config, str(effective_sls_path), args.openApiVersion)
     open_api_spec = generator.generate()
 
     try:
         with open(args.output_file_path, 'w') as f:
             json.dump(open_api_spec, f, indent=2)
-        print(f"OpenAPI specification successfully written to {args.output_file_path}")
+        rprint(f"[bold green]OpenAPI specification successfully written to {args.output_file_path}[/bold green]")
     except IOError as e:
-        print(f"Error writing to output file: {e}")
+        rprint(f"[red]Error writing to output file: {e}[/red]")
 
     if args.validate:
         from openapi_spec_validator import validate
-        print("Validating generated spec...")
+        rprint("[bold]Validating generated spec...[/bold]")
         try:
             validate(open_api_spec)
-            print("Validation successful.")
+            rprint("[bold green]Validation successful.[/bold green]")
         except Exception as e:
-            print(f"Validation failed: {e}")
+            rprint(f"[bold red]Validation failed: {e}[/bold red]")
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate OpenAPI v3 documentation from a serverless.yml file.')
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    # Sub-parser for generating schemas
+    parser_schemas = subparsers.add_parser('generate-schemas', help='Generate JSON schemas from Pydantic models.')
+    parser_schemas.add_argument('--pydantic-source', type=str, required=True, help='Path to the Pydantic models source directory')
+    parser_schemas.add_argument('--output-dir', type=str, required=True, help='Directory to save the generated JSON schemas')
+    parser_schemas.set_defaults(func=generate_schemas)
+
+    # Sub-parser for generating serverless.yml
+    parser_serverless = subparsers.add_parser('generate-serverless', help='Generate serverless.yml from JSON schemas.')
+    parser_serverless.add_argument('--schema-dir', type=str, required=True, help='Directory containing the JSON schemas')
+    parser_serverless.add_argument('--project-dir', type=str, help='Path to the project root directory (for pyproject.toml)')
+    parser_serverless.set_defaults(func=generate_serverless)
+
+    # Sub-parser for generating the OpenAPI spec
+    parser_spec = subparsers.add_parser('generate-spec', help='Generate the full OpenAPI spec from a serverless.yml file.')
+    parser_spec.add_argument('output_file_path', type=str, help='Path to the output OpenAPI JSON file')
+    parser_spec.add_argument('--serverless-yml-path', type=str, required=True, help='Path to the serverless.yml file.')
+    parser_spec.add_argument('--openApiVersion', type=str, default='3.0.3', help='OpenAPI version to use')
+    parser_spec.add_argument('--validate', action='store_true', help='Validate the generated OpenAPI spec')
+    parser_spec.set_defaults(func=generate_spec)
+
+    args = parser.parse_args()
+    args.func(args)
 
 if __name__ == '__main__':
     main()