Service API Specification [chapter] deterministic

Endpoints

• GET /users - List all users
• GET /users/{id} - Get user by ID
• POST /users - Create a new user

Data Model

User: id: int name: string email: string

`

#### Step 2: Parse the Document

We'll use a simple parser to extract the endpoints and data model:

```python import re from dataclasses import dataclass from typing import List

@dataclass class Endpoint: method: str path: str description: str

@dataclass class Field: name: str type: str

@dataclass class Model: name: str fields: List[Field]

def parse_api_spec(markdown: str): endpoints = [] models = [] # Simple regex-based parsing for line in markdown.splitlines(): m = re.match(r"^- (\w+) (.+) - (.+)$", line) if m: endpoints.append(Endpoint(m.group(1), m.group(2), m.group(3))) m = re.match(r"^(\w+):$", line) if m: model_name = m.group(1) fields = [] # Collect fields until next model or end for next_line in markdown.splitlines()[markdown.splitlines().index(line)+1:]: fm = re.match(r"^ (\w+): (\w+)$", next_line) if fm: fields.append(Field(fm.group(1), fm.group(2))) else: break models.append(Model(model_name, fields)) return endpoints, models

spec = open("api_spec.md").read() endpoints, models = parse_api_spec(spec) print(endpoints) print(models)

`

This parser extracts the endpoints and models from the markdown file, creating structured objects that can be used for code generation.

#### Step 3: Generate Code Stubs

With the parsed spec, we can generate Python stubs for the API:

```python def generate_routes(endpoints: List[Endpoint]) -> str: routes = [] for ep in endpoints: routes.append(f"@app.route('{ep.method.lower()} {ep.path}')\ndef {ep.method.lower()}_{ep.path.replace('/', '_')}():\n # TODO: Implement\n pass\n") return "\n".join(routes)

def generate_models(models: List[Model]) -> str: classes = [] for model in models: fields = "\n ".join([f"{f.name}: {f.type}" for f in model.fields]) classes.append(f"class {model.name}:\n {fields}\n") return "\n".join(classes)

print(generate_routes(endpoints)) print(generate_models(models))

`

This simple code generation step produces a basic Flask app structure with routes and data models, ready for implementation.

#### Step 4: Validate and Test

The final step is to validate the generated code against the original document. This can be done using a simple diff or by running unit tests:

```python def validate_routes(generated_routes: str, expected_routes: List[Endpoint]) -> bool: # Simple validation: check that each endpoint is present for ep in expected_routes: if f"@app.route('{ep.method.lower()} {ep.path}')" not in generated_routes: return False return True