Natuurlijk! Hier is een uitgebreide styleguide voor de REST API-documentatie van je WeerAPI, ontwikkeld met Swagger. Deze richtlijnen zorgen voor consistentie, professionaliteit en gebruiksvriendelijkheid voor ontwikkelaars en stakeholders. **1. Algemene toon en schrijfstijl** - **Toon:** Professioneel, duidelijk, objectief en vriendelijk. - **Schrijfstijl:** Actief en concreet. Gebruik korte zinnen en vermijd jargon waar mogelijk, tenzij het gangbaar is binnen de doelgroep. - **Formaliteit:** Houd de taal formeel maar toegankelijk. Vermijd informele uitdrukkingen. - **Gebruik van termen:** Consistent gebruik van terminologie zoals “endpoint”, “resource”, “statuscode”, “response”, “parameter”, “payload”, “error”, etc. **2. Terminologie en vakjargon** - Gebruik standaard REST- en API-terminologie. - Definieer specifieke termen bij eerste gebruik, bijvoorbeeld: - **Endpoint:** Het URL-adres waarop een bepaalde resource bereikbaar is. - **Request/response:** Het verzoek dat je naar de API stuurt en de reactie die je ontvangt. - **Statuscode:** HTTP-statuscode die aangeeft of het verzoek succesvol was. - **Payload:** De data die wordt verzonden of ontvangen. - Vermijd afkortingen tenzij algemeen bekend (bijvoorbeeld JSON, HTTP). **3. Opmaakstandaarden** - **Titel en koppen:** - Gebruik duidelijke hiërarchie met H1 voor de titel (“WeerAPI Documentation”). - H2 voor hoofdsecties (bv. “Endpoints”, “Authenticatie”). - H3 voor subsecties (bv. “GET /weather”). - **Codeblokken:** - Gebruik Markdown of Swagger-specifieke codebloknotatie. - Syntax: JSON voor voorbeeldpayloads, curl of HTTP voor voorbeeldverzoeken. - **Tabelgebruik:** - Voor parameters en responses, gebruik overzichtelijke tabellen met koppen zoals “Naam”, “Type”, “In”, “Beschrijving”, “Verplicht”, “Voorbeeld”. - **Consistentie:** - Gebruik dezelfde opmaak voor alle parameters en responses. - Bijvoorbeeld: parameters vetgedrukt, beschrijvingen cursief. **4. Voorbeelden en documentatie-inhoud** - **Voorbeeldverzoeken:** - Bied altijd een compleet curl-voorbeeld en, indien relevant, een voorbeeld in een programmeertaal (bijvoorbeeld JavaScript). - Voorbeeld: ```bash curl -X GET "https://api.weerapi.nl/weather?city=Amsterdam" -H "Accept: application/json" ``` - **Voorbeeldresponses:** - Geef altijd een voorbeeld van een succesvolle response en voorkomende foutmeldingen. - Gebruik JSON met duidelijke structuur en commentaar. - Voorbeeld: ```json { "city": "Amsterdam", "temperature": 15, "description": "Deel bewolkt" } ``` - **Statuscodes:** - Documenteer per endpoint de relevante statuscodes (200, 400, 404, 500, etc.) met korte uitleg. **5. Consistente terminologie in documentatie-elementen** - **Endpoint:** Gebruik altijd dezelfde notatie, bijvoorbeeld `/weather`. - **Parameters:** Geef altijd naam, type, locatie (query, path, header), verplicht of optioneel, en een voorbeeld. - **Responses:** Beschrijf gestructureerd met statuscode, beschrijving en voorbeeldpayload. - **Fouten:** Documenteer foutcodes en hun betekenis, inclusief voorbeeldfoutberichten. **6. Gebruik van Swagger-specifieke richtlijnen** - Zorg dat alle endpoints, parameters en responses correct zijn gedefinieerd volgens OpenAPI-specificaties. - Gebruik descriptieve ‘description’-velden voor uitleg. - Voeg ‘examples’ toe voor parameters en responses. - Gebruik ‘tags’ voor categorisatie (bijvoorbeeld ‘Weerdata’, ‘Authenticatie’). **7. Professionele presentatie** - Gebruik een consistente huisstijl voor titel, subtitels, tekst en code. - Vermijd overbodige decoraties en houd de layout overzichtelijk. - Zorg dat de documentatie mobielvriendelijk en goed leesbaar is. **8. Updates en versiebeheer** - Vermeld duidelijk de API-versie bovenaan. - Documenteer wijzigingen en updates in een changelog. - Gebruik semantische versies (bijvoorbeeld v1.0.0). --- Door deze richtlijnen te volgen, zorg je voor een uniforme, professionele en toegankelijke API-documentatie voor WeerAPI. Mocht je specifieke secties willen uitwerken of voorbeelden nodig hebben, laat het gerust weten!

Zeker, hier is een uitgebreide styleguide voor je WeerAPI documentatie met Swagger: # Styleguide: WeerAPI REST API Documentatie ## 1. Toon en Schrijfstijl ### Algemene Toon - **Professioneel maar toegankelijk**: Formeel genoeg voor zakelijke context, maar begrijpelijk voor ontwikkelaars - **Actieve stem**: "Retourneert de huidige temperatuur" in plaats van "De huidige temperatuur wordt geretourneerd" - **Consistent en direct**: Duidelijke, beknopte beschrijvingen zonder jargon - **Nederlandstalig**: Alle beschrijvingen in het Nederlands, behalve technische termen die standaard Engels zijn ### Gebruikersgericht - Richt je op de ontwikkelaar: "Je kunt deze endpoint gebruiken om..." - Vermijd interne bedrijfstermen tenzij essentieel - Toon empathie voor gebruikerservaring ## 2. Terminologie en Benamingen ### API-specifieke Termen - **WeerAPI**: Altijd met hoofdletter W en A, zonder spatie - **Endpoint**: Gebruik "endpoint" in plaats van "URL" of "route" - **Parameter**: Gebruik "parameter" voor query, path en header parameters - **Response**: Gebruik "response" voor API-antwoorden ### Weergerelateerde Termen - **Temperatuur**: Altijd in graden Celsius (°C) - **Neerslag**: Gebruik "neerslag" in plaats van "regen/sneeuw" - **Luchtdruk**: In hectopascal (hPa) - **Vochtigheid**: In percentage (%) - **Windsnelheid**: In meter per seconde (m/s) ### Technische Termen - Gebruik Engelse technische termen: GET, POST, JSON, HTTP status codes - **API-sleutel**: Gebruik "API-sleutel" in het Nederlands - **Authenticatie**: Gebruik "authenticatie" in het Nederlands ## 3. Opmaakstandaarden ### Structuur en Organisatie ``` WeerAPI Documentatie ├── Introductie ├── Authenticatie ├── Endpoints │ ├── Huidig Weer │ ├── Weersvoorspelling │ ├── Historische Data │ └── Weeralarmen └── Foutafhandeling ``` ### Beschrijvingsformaat **Endpoint beschrijving:** ``` [HTTP Method] [Endpoint pad] Korte, duidelijke beschrijving van de functionaliteit. Parameters: - parameter1 (type): Beschrijving [verplicht/optioneel] - parameter2 (type): Beschrijving [verplicht/optioneel] Response: Success: HTTP 200 met JSON object Error: HTTP 4xx/5xx met foutmelding ``` ### Code Voorbeelden ```json { "location": "Amsterdam", "temperature": 15.5, "humidity": 78, "weather_condition": "bewolkt" } ``` ## 4. Documentatie Elementen ### API Info Sectie ```yaml openapi: 3.0.0 info: title: WeerAPI description: "REST API voor actuele weersinformatie en voorspellingen" version: 1.0.0 contact: name: WeerAPI Support email: support@weerapi.nl ``` ### Endpoint Template ```yaml /weer/huidig: get: summary: "Haal huidige weersinformatie op" description: "Retourneert de actuele weersomstandigheden voor een specifieke locatie" parameters: - name: stad in: query required: true description: "Naam van de stad" schema: type: string example: "Utrecht" responses: '200': description: "Succesvolle response met weersdata" content: application/json: schema: $ref: '#/components/schemas/WeerData' ``` ### Response Schema's ```yaml components: schemas: WeerData: type: object properties: locatie: type: string description: "Naam van de locatie" example: "Rotterdam" temperatuur: type: number format: float description: "Huidige temperatuur in °C" example: 18.5 weersomstandigheid: type: string description: "Beschrijving weersomstandigheid" example: "zonnig" luchtvochtigheid: type: integer description: "Relatieve luchtvochtigheid in %" example: 65 ``` ## 5. Foutafhandeling ### Foutresponse Standaard ```json { "error": { "code": "INVALID_LOCATION", "message": "De opgegeven locatie kon niet worden gevonden", "details": "Controleer de spelling van de stadnaam" } } ``` ### HTTP Status Codes - **200**: Succes - **400**: Ongeldige request parameters - **401**: Ongeautoriseerd (ontbrekende API-sleutel) - **404**: Locatie niet gevonden - **429**: Te veel requests (rate limiting) - **500**: Interne serverfout ## 6. Voorbeelden en Use Cases ### Praktijkvoorbeelden **Voorbeeld 1: Huidig weer opvragen** ``` GET /weer/huidig?stad=Amsterdam&land=NL API-Sleutel: jullie-api-sleutel-hier ``` **Response:** ```json { "locatie": "Amsterdam, NL", "temperatuur": 12.5, "gevoelstemperatuur": 10.8, "weersomstandigheid": "licht bewolkt", "luchtvochtigheid": 75, "windsnelheid": 4.2, "luchtdruk": 1013, "zon_opkomst": "06:45", "zon_onder": "18:30" } ``` **Voorbeeld 2: Weersvoorspelling** ``` GET /weer/voorspelling?stad=Eindhoven&dagen=5 ``` ## 7. Consistentie Checklist - [ ] Alle endpoint beschrijvingen in het Nederlands - [ ] Technische termen consistent gespeld - [ ] Eenheden duidelijk aangegeven (°C, %, m/s, hPa) - [ ] Foutmeldingen volgen het standaard format - [ ] Voorbeelden zijn realistisch en relevant - [ ] Parameters hebben duidelijke beschrijvingen - [ ] Verplichte/optionele parameters zijn gemarkeerd - [ ] Response voorbeelden zijn compleet ## 8. Onderhoud en Updates - Houd een changelog bij voor API wijzigingen - Markeer deprecated endpoints duidelijk - Voorzie migration guides voor breaking changes - Review documentatie bij elke API update Deze styleguide zorgt voor professionele, consistente documentatie die zowel ontwikkelaars als stakeholders waarderen. Pas deze richtlijnen strikt toe voor de beste gebruikerservaring.