Natuurlijk! Hieronder vind je een voorbeeld van een Python-script dat automatisch documentatie genereert voor je RESTful API op basis van gedefinieerde eindpunten. Dit script veronderstelt dat je API wordt beschreven met een gestructureerd dataformaat, bijvoorbeeld via een Python-dictionary, of dat je je API-endpoints en bijbehorende details kunt extraheren uit je code of configuratie. Het script genereert Markdown-documentatie die makkelijk te lezen en te updaten is. Je kunt dit uitbreiden of aanpassen afhankelijk van hoe je API is opgebouwd. --- ### Voorbeeld Python-script voor automatische API-documentatie in Markdown ```python import datetime # Voorbeeld van je API endpoints. Dit moet je aanpassen aan jouw situatie. api_endpoints = [ { "path": "/gebruikers", "method": "GET", "parameters": [], "response": { "status": 200, "body": [ {"id": 1, "naam": "Jan", "email": "jan@example.com"}, {"id": 2, "naam": "Piet", "email": "piet@example.com"} ] }, "description": "Haalt een lijst van alle gebruikers op." }, { "path": "/gebruikers", "method": "POST", "parameters": [ {"name": "naam", "type": "string", "required": True, "description": "Naam van de gebruiker"}, {"name": "email", "type": "string", "required": True, "description": "E-mailadres van de gebruiker"} ], "response": { "status": 201, "body": {"id": 3, "naam": "Klaas", "email": "klaas@example.com"} }, "description": "Voegt een nieuwe gebruiker toe." }, # Voeg meer eindpunten toe zoals nodig ] def generate_markdown(api_endpoints): # Titel en datum md = f"# API Documentatie\n\n" md += f"**Datum:** {datetime.date.today().strftime('%d-%m-%Y')}\n\n" # Inleiding md += "Deze documentatie beschrijft de beschikbare API-eindpunten.\n\n" # Overzicht van alle eindpunten md += "## Overzicht van Eindpunten\n\n" for ep in api_endpoints: md += f"- **[{ep['method']} {ep['path']}]**: {ep['description']}\n" md += "\n---\n\n" # Detail per eindpunt for ep in api_endpoints: md += f"### {ep['method']} {ep['path']}\n\n" md += f"{ep['description']}\n\n" md += f"**Request Methode:** `{ep['method']}`\n\n" md += f"**Path:** `{ep['path']}`\n\n" if ep['parameters']: md += "**Parameters:**\n\n" md += "| Naam | Type | Vereist | Beschrijving |\n" md += "|-------|-------|---------|--------------|\n" for param in ep['parameters']: req = "Ja" if param['required'] else "Nee" md += f"| {param['name']} | {param['type']} | {req} | {param.get('description', '-') } |\n" md += "\n" else: md += "Geen parameters.\n\n" # Response resp = ep['response'] md += "**Response:**\n\n" md += f"- **Status:** {resp['status']}\n" md += "- **Body:**\n\n" md += "```json\n" import json md += json.dumps(resp['body'], indent=4) md += "\n```\n\n" md += "---\n\n" return md # Genereer de markdown markdown_content = generate_markdown(api_endpoints) # Opslaan in een bestand with open("API_documentatie.md", "w", encoding="utf-8") as f: f.write(markdown_content) print("API documentatie is gegenereerd en opgeslagen als 'API_documentatie.md'.") ``` --- ### Hoe gebruik je dit script? 1. **Pas de `api_endpoints` lijst aan** met je eigen API-eindpunten, inclusief methoden, paden, parameters, response-formaten en beschrijvingen. 2. **Voer het script uit**. Het genereert een Markdown-bestand (`API_documentatie.md`) dat je kunt bekijken en updaten. 3. **Voor updates**: voeg nieuwe eindpunten toe of pas bestaande aan in de `api_endpoints` lijst; herhaal het script. ### Structuur van de gegenereerde documentatie (voorbeeld) ```markdown # API Documentatie **Datum:** 27-04-2024 Deze documentatie beschrijft de beschikbare API-eindpunten. ## Overzicht van Eindpunten - **[GET /gebruikers]**: Haalt een lijst van alle gebruikers op. - **[POST /gebruikers]**: Voegt een nieuwe gebruiker toe. --- ### GET /gebruikers Haalt een lijst van alle gebruikers op. **Request Methode:** `GET` **Path:** `/gebruikers` **Parameters:** Geen parameters. **Response:** - **Status:** 200 - **Body:** ```json [ { "id": 1, "naam": "Jan", "email": "jan@example.com" }, { "id": 2, "naam": "Piet", "email": "piet@example.com" } ] ``` --- ### POST /gebruikers Voegt een nieuwe gebruiker toe. **Request Methode:** `POST` **Path:** `/gebruikers` **Parameters:** | Naam | Type | Vereist | Beschrijving | |---------|---------|----------|-----------------------------------| | naam | string | Ja | Naam van de gebruiker | | email | string | Ja | E-mailadres van de gebruiker | **Response:** - **Status:** 201 - **Body:** ```json { "id": 3, "naam": "Klaas", "email": "klaas@example.com" } ``` --- Je kunt deze structuur uitbreiden met authenticatie, meer details, voorbeeldaanroepen, enz. Op deze manier blijft je documentatie makkelijk te onderhouden en te updaten naarmate je API evolueert.

Hier is een Python-script dat automatisch API-documentatie genereert met Flask-achtige route decorators: ```python import inspect import os from typing import Dict, List, Any import json class APIDocumentationGenerator: def __init__(self, app_instance=None): self.app = app_instance self.endpoints = [] def add_endpoint(self, path: str, methods: List[str], parameters: List[Dict] = None, responses: Dict = None, description: str = "", example_request: Dict = None, example_response: Dict = None): """Voeg een API endpoint handmatig toe""" endpoint = { 'path': path, 'methods': methods, 'parameters': parameters or [], 'responses': responses or {}, 'description': description, 'example_request': example_request, 'example_response': example_response } self.endpoints.append(endpoint) def extract_flask_routes(self): """Extraheer routes van een Flask applicatie""" if not self.app: return for rule in self.app.url_map.iter_rules(): if rule.endpoint != 'static': endpoint = { 'path': str(rule), 'methods': list(rule.methods - {'OPTIONS', 'HEAD'}), 'parameters': self._extract_parameters_from_rule(rule), 'description': self._get_endpoint_description(rule.endpoint), 'responses': {}, 'example_request': None, 'example_response': None } self.endpoints.append(endpoint) def _extract_parameters_from_rule(self, rule): """Extraheer parameters uit Flask route rule""" parameters = [] for converter, arg_name in rule._converters.items(): parameters.append({ 'name': arg_name, 'type': converter, 'required': True, 'description': f'URL parameter: {arg_name}' }) return parameters def _get_endpoint_description(self, endpoint_name): """Haal beschrijving op uit docstring van view functie""" view_func = self.app.view_functions.get(endpoint_name) if view_func and view_func.__doc__: return view_func.__doc__.strip().split('\n')[0] return "Geen beschrijving beschikbaar" def generate_markdown(self, title: str = "API Documentatie") -> str: """Genereer Markdown documentatie""" md = f"# {title}\n\n" for endpoint in self.endpoints: md += self._format_endpoint_markdown(endpoint) return md def _format_endpoint_markdown(self, endpoint: Dict) -> str: """Formatteer een enkel endpoint in Markdown""" section = f"## `{endpoint['path']}`\n\n" section += f"**Beschrijving:** {endpoint['description']}\n\n" # Methoden section += "**Methoden:** " + ", ".join(f"`{m}`" for m in endpoint['methods']) + "\n\n" # Parameters if endpoint['parameters']: section += "### Parameters\n\n" section += "| Naam | Type | Verplicht | Beschrijving |\n" section += "|------|------|-----------|--------------|\n" for param in endpoint['parameters']: required = "Ja" if param.get('required', False) else "Nee" section += f"| {param['name']} | {param.get('type', 'string')} | {required} | {param.get('description', '')} |\n" section += "\n" # Responses if endpoint['responses']: section += "### Responses\n\n" for code, description in endpoint['responses'].items(): section += f"- **{code}:** {description}\n" section += "\n" # Voorbeelden if endpoint['example_request']: section += "### Voorbeeld Request\n\n" section += "```json\n" section += json.dumps(endpoint['example_request'], indent=2) section += "\n```\n\n" if endpoint['example_response']: section += "### Voorbeeld Response\n\n" section += "```json\n" section += json.dumps(endpoint['example_response'], indent=2) section += "\n```\n\n" section += "---\n\n" return section def generate_html(self, title: str = "API Documentatie") -> str: """Genereer HTML documentatie""" html = f""" <!DOCTYPE html> <html> <head> <title>{title}</title> <style> body {{ font-family: Arial, sans-serif; margin: 40px; }} .endpoint {{ border: 1px solid #ddd; margin: 20px 0; padding: 20px; border-radius: 5px; }} .path {{ font-size: 1.2em; font-weight: bold; color: #333; }} .method {{ display: inline-block; background: #007bff; color: white; padding: 2px 8px; border-radius: 3px; margin-right: 5px; }} table {{ border-collapse: collapse; width: 100%; margin: 10px 0; }} th, td {{ border: 1px solid #ddd; padding: 8px; text-align: left; }} th {{ background-color: #f2f2f2; }} pre {{ background: #f4f4f4; padding: 10px; border-radius: 3px; overflow-x: auto; }} </style> </head> <body> <h1>{title}</h1> """ for endpoint in self.endpoints: html += self._format_endpoint_html(endpoint) html += "</body></html>" return html def _format_endpoint_html(self, endpoint: Dict) -> str: """Formatteer een enkel endpoint in HTML""" methods_html = "".join(f'<span class="method">{m}</span>' for m in endpoint['methods']) html = f""" <div class="endpoint"> <div class="path">{endpoint['path']}</div> <div class="methods">{methods_html}</div> <p><strong>Beschrijving:</strong> {endpoint['description']}</p> """ # Parameters tabel if endpoint['parameters']: html += "<h3>Parameters</h3><table>" html += "<tr><th>Naam</th><th>Type</th><th>Verplicht</th><th>Beschrijving</th></tr>" for param in endpoint['parameters']: required = "Ja" if param.get('required', False) else "Nee" html += f"<tr><td>{param['name']}</td><td>{param.get('type', 'string')}</td><td>{required}</td><td>{param.get('description', '')}</td></tr>" html += "</table>" # Responses if endpoint['responses']: html += "<h3>Responses</h3><ul>" for code, description in endpoint['responses'].items(): html += f"<li><strong>{code}:</strong> {description}</li>" html += "</ul>" # Voorbeelden if endpoint['example_request']: html += "<h3>Voorbeeld Request</h3>" html += f"<pre>{json.dumps(endpoint['example_request'], indent=2)}</pre>" if endpoint['example_response']: html += "<h3>Voorbeeld Response</h3>" html += f"<pre>{json.dumps(endpoint['example_response'], indent=2)}</pre>" html += "</div>" return html def save_to_file(self, filename: str, format_type: str = 'markdown'): """Sla documentatie op in bestand""" if format_type.lower() == 'markdown': content = self.generate_markdown() ext = '.md' elif format_type.lower() == 'html': content = self.generate_html() ext = '.html' else: raise ValueError("Ongeldig formaat. Kies 'markdown' of 'html'") if not filename.endswith(ext): filename += ext with open(filename, 'w', encoding='utf-8') as f: f.write(content) print(f"Documentatie opgeslagen als: {filename}") # VOORBEELD GEBRUIK if __name__ == "__main__": # Maak generator instance doc_gen = APIDocumentationGenerator() # Voeg endpoints handmatig toe (of gebruik extract_flask_routes() voor Flask apps) doc_gen.add_endpoint( path="/api/users", methods=["GET", "POST"], description="Beheer gebruikers", parameters=[ {"name": "page", "type": "integer", "required": False, "description": "Paginanummer"}, {"name": "limit", "type": "integer", "required": False, "description": "Aantal items per pagina"} ], responses={ "200": "Success", "400": "Ongeldige request", "500": "Server error" }, example_request={ "method": "GET", "url": "/api/users?page=1&limit=10" }, example_response={ "users": [ {"id": 1, "name": "Jan Jansen", "email": "jan@voorbeeld.nl"}, {"id": 2, "name": "Piet Pieters", "email": "piet@voorbeeld.nl"} ], "total": 2, "page": 1 } ) doc_gen.add_endpoint( path="/api/users/{user_id}", methods=["GET", "PUT", "DELETE"], description="Beheer specifieke gebruiker", parameters=[ {"name": "user_id", "type": "integer", "required": True, "description": "Gebruiker ID"} ], responses={ "200": "Success", "404": "Gebruiker niet gevonden" } ) # Genereer documentatie markdown_docs = doc_gen.generate_markdown("Mijn API Documentatie") print("Markdown output:\n") print(markdown_docs) # Sla op in bestanden doc_gen.save_to_file("api_documentatie", "markdown") doc_gen.save_to_file("api_documentatie", "html") # Gebruik met Flask (optioneel) def setup_flask_documentation(app): """Voorbeeld: Integratie met Flask app""" doc_gen = APIDocumentationGenerator(app) doc_gen.extract_flask_routes() # Voeg aanvullende informatie toe for endpoint in doc_gen.endpoints: if endpoint['path'] == '/api/users': endpoint['description'] = "Haal gebruikerslijst op of maak nieuwe gebruiker aan" return doc_gen ``` ## Voorbeeld Documentatie Structuur: ### Markdown Output: ```markdown # Mijn API Documentatie ## `/api/users` **Beschrijving:** Beheer gebruikers **Methoden:** `GET`, `POST` ### Parameters | Naam | Type | Verplicht | Beschrijving | |------|------|-----------|--------------| | page | integer | Nee | Paginanummer | | limit | integer | Nee | Aantal items per pagina | ### Responses - **200:** Success - **400:** Ongeldige request - **500:** Server error ### Voorbeeld Request ```json { "method": "GET", "url": "/api/users?page=1&limit=10" } ``` ### Voorbeeld Response ```json { "users": [ { "id": 1, "name": "Jan Jansen", "email": "jan@voorbeeld.nl" }, { "id": 2, "name": "Piet Pieters", "email": "piet@voorbeeld.nl" } ], "total": 2, "page": 1 } ``` --- ``` ## Gebruiksaanwijzing: 1. **Basis gebruik**: Run het script om documentatie te genereren 2. **Flask integratie**: Gebruik `setup_flask_documentation(app)` voor automatische route-extractie 3. **Handmatig toevoegen**: Gebruik `add_endpoint()` voor niet-Flask APIs 4. **Updates**: Voeg nieuwe endpoints toe via `add_endpoint()` of update bestaande 5. **Output**: Kies tussen Markdown (`.md`) of HTML (`.html`) formaat ## Onderhoud en Updates: - Bewaar het script in je project repository - Voeg nieuwe endpoints toe wanneer je API groeit - Update bestaande endpoints wanneer parameters veranderen - Genereer documentatie opnieuw na wijzigingen - Integreer in je CI/CD pipeline voor automatische updates Dit script is modulair opgebouwd en eenvoudig aan te passen voor specifieke framework-vereisten!